@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/timeline.md

@@ -0,0 +1,333 @@
+# Timeline
+
+Time as a value: an object animated through keyframes, and actions fired when
+time reaches them.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/timeline` |
+
+---
+
+## What it does
+
+A Timeline animates **one object** (typically an image, given as a Canvas
+drawing instruction) through **keyframes** for its properties: where it is, how
+big, how far turned, how opaque. It emits the object as it is at each moment.
+It also carries **actions**: data placed at a moment and emitted when time
+reaches it.
+
+Nothing is scheduled per action. A timeline takes a time `t` and works out
+what lies between the time it last saw and the time it sees now. That is what
+lets it be paused, sought and looped, and the same time always gives the same
+output.
+
+Timelines nest. An outer timeline keeps the clock and drives the inner ones by
+passing time down the pipeline. The outer one also says, by name, when each
+inner one plays (see *Placements*). Several animated pieces are mixed with
+[Tracks](./tracks.md), one track per piece, onto one [Canvas](./canvas.md).
+
+---
+
+## Where time comes from
+
+`clock` decides it:
+
+| `clock` | Time comes from | Used for |
+|---|---|---|
+| `"own"` (default) | Its own clock, emitting `fps` frames a second while it plays. Its input is an action happening now (see [Recording](#recording)). | The outermost timeline, the one the facade starts and stops, and a timeline recording what arrives |
+| `"input"` | The frames it is given: `t` from the input (or a bare number), in whatever unit the driver counts | Every inner timeline |
+
+An own clock counts in seconds or in **beats** (`unit`). Beats read the tempo
+held in the slot `tempoSlot` names, as [Timer](./timer.md#beats) does. The
+tempo is read every frame, so a change applies from the next frame. With no
+tempo held, a beat is counted at 120 BPM.
+
+Counting beats, every frame carries the **`tempo`** it was counted at, and a
+driven timeline passes it on. What follows can then turn beats into time
+without reaching the slot, which a service inside a Tracks track cannot: a
+[Sound](./sound.md#envelope) holds its notes for beats of it.
+
+### Length and looping
+
+`length` 0 is unbounded. A non-looping timeline's positions are
+`[0, length]`.
+
+A looping timeline repeats its **loop range**, `[loopStart, loopEnd)`. By
+default the range is the whole timeline (`loopStart` 0, and `loopEnd` 0 means
+the length), so a looping timeline wraps at `length`. An action at the range's
+end never fires, because that moment is the next pass's start.
+
+- Time before `loopStart` plays once, on the way into the range, like a count-in.
+- What lies past `loopEnd` does not play while the timeline loops. Switch
+  looping off and everything plays again; `length` stays where a non-looping
+  timeline ends.
+- An own clock set past the range's end goes to its start. That applies when
+  it is sought there, when it stands there as it starts playing, and when the
+  range moves to before where it stands.
+- An unbounded timeline (`length` 0) loops only with a `loopEnd`.
+
+- An own clock that does not loop halts at its end. Playing again starts over.
+- A driven timeline that does not loop emits **null** past its end, so the
+  pipeline behind it does not run. The one exception is the frame that leaves
+  the stretch: if an action or the end of a placement fell due on the way out,
+  that frame is emitted at the edge (`t` = `length`).
+
+### A jump is not a wrap
+
+A driven timeline sees time go backwards both when its driver loops and when
+its driver is sought backwards. The two need opposite answers:
+
+- The frame after a seek carries **`jump: true`**. Time was set, not
+  travelled, so only what sits exactly there fires.
+- Time going backwards **without** `jump` means the driver started over (a
+  loop, or a stop and play). The driven timeline settles what it still owed
+  from the pass it was in, then starts its own from the beginning.
+
+A timeline passes `jump` on, so a seek is a seek at every level.
+
+---
+
+## The object and its keyframes
+
+`object` is any JSON object, usually a drawing instruction.
+`keyframes` maps each animated property to the moments it passes through:
+
+```json
+"object": { "type": "image", "url": "…", "height": "20%" },
+"keyframes": {
+  "rotate":  [ { "at": 0, "value": 0, "ease": "in-out" }, { "at": 3, "value": 360 } ],
+  "centerX": [ { "at": 0, "value": "10%" }, { "at": 3, "value": "90%" } ]
+}
+```
+
+- Before its first keyframe a property holds that keyframe's value; after its
+  last, the last one's.
+- In between it travels from the keyframe before `t` to the one after, eased
+  by the earlier keyframe's `ease`: `linear` (default), `in`, `out`, `in-out`
+  (cubic), or `step` (hold until the next).
+- Numbers interpolate, as do strings that are a number with the same suffix at
+  both ends (`"30%"` to `"70%"`) and `#rrggbb` colours. Anything else holds.
+- Two keyframes at the same moment make the value jump there.
+
+---
+
+## Actions
+
+Actions are `{ "at": <number>, "data": <anything> }`. An action is due in a
+frame when its time lies in `(previous t, t]`. It is also due when it sits
+exactly where time was set: playing from the start, or a seek. Several actions
+at one moment all fire, in list order. A frame can cover several passes of a
+loop and fires the actions of each. An action without data is reported as null.
+
+Because actions fire only when time passes over them, a seek skips them. For
+state that must be right wherever time lands ("from here on, scene B"), use a
+keyframe with `step` ease instead.
+
+---
+
+## Recording
+
+Whatever arrives at an own clock's input is an **action happening now**. The
+timeline does not look at what it is: a pad's audio, a note, a click, a line of
+text are all recorded and played back the same way.
+
+- **Playing:** the clock moves to the moment the input arrived (that exact
+  moment, not the last frame's) and the input leaves in that frame's
+  `actions`, after anything else due by then.
+- **Recording** (`recording: true`, while playing): the input also stays, as
+  `{ "at": <that moment>, "data": <the input> }`. From then on it plays
+  whenever time reaches it, like any other action: faster or slower with
+  `speed`, and again on every pass of a loop.
+- **Stopped or paused:** the input passes through on a frame for where the
+  timeline stands, `{ "t": …, "actions": [<the input>] }`. Nothing is recorded,
+  so what follows sees the same shape whether the timeline plays or not.
+
+`recordMode` says what a recording does to the actions already there:
+
+| Mode | While recording |
+|---|---|
+| `"overdub"` (default) | What is there stays and plays; new actions are added to it |
+| `"replace"` | What time passes over is cleared: it neither fires nor stays. What lies past the point where recording stopped is kept. On a loop, each pass replaces the one before. |
+
+Stopping or pausing ends a recording, so playing a take back never records over
+it. Recorded actions are saved with the board like any others, but only as
+far as their data is JSON: audio (a Blob) lasts only while the board is open.
+
+Actions are emitted on the first frame at or after their moment, so a recorded
+action plays back up to one frame (`1 / fps` seconds) late. Raise `fps` for
+tighter timing.
+
+---
+
+## Placements
+
+Placements arrange driven timelines on the one driving them, **by name**. The
+outer timeline's `placements` say when each name plays and for how long. An
+inner timeline's `placement` says which name it takes. Neither knows where the
+other sits: the name is all they share, as two [Holds](./hold.md) share a slot.
+
+```json
+// outer
+"placements": [
+  { "name": "star-1", "at": 0,   "duration": 3 },
+  { "name": "rocket", "at": 2.5, "duration": 4 },
+  { "name": "star-1", "at": 6,   "duration": 1.5 }
+]
+
+// inner, e.g. inside a block whose param names it
+{ "clock": "input", "placement": "{{param.name}}" }
+```
+
+Each frame the outer timeline emits carries `placements`: for **every** name it
+places, `{ "progress", "elapsed" }` while that name plays (`progress` 0 to 1
+through the placement, `elapsed` the outer time since it started), and `null`
+while it does not.
+
+| Rule | Behaviour |
+|---|---|
+| Stretching | A non-looping inner timeline with a length is **stretched** to its placement: its time is `progress × length`. A looping or unbounded one plays at its own speed (`elapsed`) and, if it loops, repeats for as long as the placement lasts. |
+| The end | A placement that ends between two frames is reported once more, at its end (`progress` 1), so its final pose and any action at its end are not skipped. |
+| Not playing | While its name is not playing, a placed timeline emits null. |
+| Entering | A name that starts playing without a jump enters from its start: what sits at 0 fires. |
+| The same name twice | Allowed. Where two placements of a name overlap, the one that started later wins. |
+| Scoping | A timeline's frames carry **its own** placements only, replacing its driver's, so each level sees the names of the one directly driving it. |
+| Looping outer timeline | Placements lie within `[0, length)`; one running past the end is cut there. |
+| Not placed | A driven timeline without `placement` reads `t` from its input. |
+
+A mistyped name is a contract nothing checks, so a placed timeline reports its
+`placementStatus`:
+
+| Status | Meaning |
+|---|---|
+| `playing` | Its name is playing now |
+| `waiting` | Its name is placed, but not at this time |
+| `unplaced` | Frames place other names, never this one: most likely a name mistyped on one side |
+| `no-placements` | Frames place nothing at all |
+
+Its panel warns on `unplaced` and `no-placements`.
+
+Everything between two timelines must pass `placements` on. Tracks,
+sub-services and Switch do. A [Map](./map.md) in replace mode drops it, as it
+drops `t`.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `clock` | `"own" \| "input"` | `"own"` | Where time comes from |
+| `object` | `object \| null` | `null` | What the timeline animates |
+| `keyframes` | `{ [property]: { at, value, ease? }[] }` | `{}` | Keyframes per property of the object |
+| `actions` | `{ at, data }[]` | `[]` | Data emitted when time reaches `at` |
+| `length` | `number` | `0` | Length in the timeline's unit; `0` is unbounded |
+| `loop` | `boolean` | `false` | Repeat the loop range |
+| `loopStart` | `number` | `0` | Where the loop starts over from |
+| `loopEnd` | `number` | `0` | Where the loop starts over; `0` is the length |
+| `unit` | `"s" \| "beats"` | `"s"` | How an own clock counts |
+| `tempoSlot` | `string` | `"tempo"` | Slot holding the tempo (BPM) for `"beats"` |
+| `fps` | `number` | `30` | Frames a second an own clock emits |
+| `speed` | `number` | `1` | Playback speed of an own clock |
+| `running` | `boolean` | `false` | Whether an own clock is playing; `true` plays, `false` pauses |
+| `recording` | `boolean` | `false` | Whether what arrives at a playing own clock's input is kept as actions. Stopping or pausing sets it to `false`. |
+| `recordMode` | `"overdub" \| "replace"` | `"overdub"` | Whether a recording keeps the actions it passes over or clears them |
+| `placements` | `{ name, at, duration }[]` | `[]` | When each name plays on this timeline |
+| `placement` | `string` | `""` | The name a driven timeline takes from its driver; `""` takes none |
+
+### Commands
+
+Only an own clock responds to these.
+
+| Command | Effect |
+|---|---|
+| `play: true` | Plays from where it is (from the start if it played through to its end), emitting a frame at once |
+| `pause: true` | Pauses where it is |
+| `stop: true` | Pauses and goes back to 0 |
+| `recording: true` | Records what arrives at the input while playing. Send it with `play: true` to start playing and recording at once. |
+| `seek: <number>` | Sets the time. Paused, a frame is emitted at once, so scrubbing a paused timeline scrubs everything it drives. The next frame carries `jump: true`. |
+
+Changing `object`, `keyframes` or `placements` re-emits the current frame
+without firing anything, so an edit shows while paused. While bypassed, an own
+clock keeps time but emits nothing.
+
+---
+
+## Input and output
+
+A driven timeline takes a frame `{ "t": <number>, "placements"?: {…}, "jump"?: true }`
+or a bare number. An own clock takes anything, as an action happening now; no
+input (`null` or `undefined`) emits nothing.
+
+It emits **every frame**, not only those an action falls in, because what
+follows has to redraw:
+
+```json
+{ "type": "image", "url": "…", "height": "20%", "rotate": 180, "centerX": "50%",
+  "t": 1.5, "actions": [], "placements": { "star-1": { "progress": 0.5, "elapsed": 1.5 } } }
+```
+
+- With an `object`: the object with each keyframed property at its value, plus
+  `t` and `actions`. It does not take on its driver's fields, except `jump`. A
+  timeline animating a drawing instruction therefore emits a drawing
+  instruction, and a Canvas draws it directly, ignoring the other fields.
+- Without one: a driven timeline keeps its input's other fields and overwrites
+  `t` and `actions`, so a frame can carry more than time down through nested
+  timelines.
+- `placements` appears when the timeline places names, or when its input
+  carried `placements`, and holds this timeline's own.
+- `null` where a driven timeline is outside its stretch or its placement is
+  not playing.
+
+---
+
+## The panel
+
+Compact, the panel shows the transport, a preview drawn with the Canvas
+service's drawing code, the ruler, one lane with every keyframe and action, and
+the placements beneath. Expanded, it grows to one row per property (value at
+the playhead, a ◆ to set or remove a keyframe there), one per placed name (bars
+to drag and resize), and one for the actions.
+
+- A property that is not animated has a fixed value on the object. Once it has
+  a keyframe, a value typed at the playhead sets a keyframe there.
+- The strip above the ruler shows the loop range. Drag across it to draw a
+  new range, which also switches looping on. Drag the range to move it, or drag
+  an edge to move that edge. Press the range to switch looping on or off. The
+  repeat button in the transport switches looping too. While looping, the
+  range is shaded over the rows, and the expanded view has `from` and `to`
+  fields for it.
+- The record button in the transport records what arrives while playing; the
+  button beside it switches between `overdub` and `replace`. Recorded data that
+  is not JSON (a Blob) is described on its marker rather than written out, and
+  cannot be edited as text.
+- The image button in the transport, or dropping an image on the preview, sets
+  the object's image, kept as a data URL.
+- Scrubbing an own clock seeks it, and so moves the whole board. A driven
+  timeline's playhead is its driver's: scrubbing pins it for editing, and
+  "live" follows the driver again.
+- Inside a [block](../concepts/blocks.md) use the panel is read-only: keyframes
+  and actions can be picked and read, but nothing configures the service.
+
+---
+
+## Example
+
+`boards/timeline-demo-board.json` keeps the clock in a
+**Show** timeline (eight seconds, looping) that feeds a Tracks scene, one track
+per image, onto one Canvas. Two blocks write the motions once (**Pop** and
+**Fly**) and each use names the placement it plays under. The Show's
+placements say when each plays and for how long.
+
+`boards/night-groove-demo-board.json` puts a drum groove under the same sky.
+Its Show counts in beats at a tempo held in a slot, and places drums and
+images alike. Each drum is a looping timeline whose actions are its hits,
+followed by a Sound.
+
+`boards/pad-groove-demo-board.json` is the same idea with no picture: a pad,
+a bass line and drums. Its chords are several actions at one moment, played by
+a synth that holds them for beats of the tempo on the frame.

package/bundle/docs/content/services/timer.md

@@ -0,0 +1,113 @@
+# Timer
+
+Generates periodic or one-shot timing events to drive pipeline execution.
+
+---
+
+## Overview
+
+The Timer service produces trigger events on a time-based schedule. It supports two operating modes: **periodic** (repeating interval) and **one-shot** (fires once after a delay). Each trigger increments an internal counter and emits the current count downstream.
+
+**Available in:**
+- Browser Runtime — service ID `hookup.to/service/timer`
+- hkp-node — service ID `timer`
+- hkp-python — service ID `timer` (also answers to `hookup.to/service/timer`, the
+  id it used before it matched the other runtimes; that alias is not advertised
+  in the registry)
+- hkp-rt — service ID `timer`
+
+---
+
+## Operating Modes
+
+| Mode | How it works | Relevant properties |
+|---|---|---|
+| **Periodic** | Fires repeatedly on a fixed interval using `setInterval` | `periodic: true`, `periodicValue`, `periodicUnit` |
+| **One-shot** | Fires once after a delay using `setTimeout` | `periodic: false` (default), `oneShotDelay`, `oneShotDelayUnit` |
+
+Setting `immediate: true` in either mode causes the first tick to fire almost instantly (1 ms) before the regular schedule begins.
+
+### As a delay
+
+A one-shot Timer placed in a pipeline also delays what flows through it: `process` waits `oneShotDelay`, then passes its input on with `triggerCount` added; a delay of zero passes it on at once, without yielding. Each input waits on its own, so one arriving while an earlier one is still waiting is not dropped or let through early, but held for its full delay too. A periodic Timer passes its input straight through. The [Nested Rhythm](../boards/nested-rhythm-demo-board.md) board times a whole drum groove this way.
+
+### Beats
+
+**Browser only.** `"beats"` as `periodicUnit` or `oneShotDelayUnit` measures a duration in beats of a tempo held in a [slot](./hold.md#where-its-cells-live), named by `tempoSlot`. `oneShotDelay: 0.5` in beats is an eighth note; `periodicValue: 4` is a bar of 4/4. The slot holds a number of beats per minute, usually written by a [Hold](./hold.md) given a `value`. With no tempo held, a beat is counted at 120 BPM.
+
+The slot is read each time a duration is needed rather than when the Timer is configured. A delay picks up a new tempo on its next wait. A periodic Timer in beats schedules one tick at a time, each at the tempo held when its interval starts, so a change applies from the tick after the one already scheduled. Because the tempo is looked up rather than configured, it can sit in the outermost of several nested [scopes](../concepts/scopes.md) and reach every Timer inside the ones that inherit its slots.
+
+`"bpm"` is different: it is a *rate* for a periodic Timer (`periodicValue: 120, periodicUnit: "bpm"` ticks 120 times a minute) and reads no slot.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `periodic` | `boolean` | `false` | When `true`, the timer fires repeatedly at the configured interval. When `false`, fires once. |
+| `periodicValue` | `number` | `1` | Numeric amount for the repeating interval. Interpreted in `periodicUnit`. |
+| `periodicUnit` | `string` | `"s"` | Time unit for `periodicValue`. Accepts any [moment.js duration unit](https://momentjs.com/docs/#/durations/): `"ms"`, `"s"`, `"m"`, `"h"`, `"d"`, etc., as well as the rates `"bpm"` and `"hz"` and, in the browser, `"beats"`. |
+| `oneShotDelay` | `number` | `0` | Delay before a one-shot timer fires. |
+| `oneShotDelayUnit` | `string` | `"ms"` | Time unit for `oneShotDelay`: `"ms"`, `"s"`, `"beats"`, or any moment.js unit. |
+| `tempoSlot` | `string` | `"tempo"` | **Browser only.** The slot a `"beats"` duration reads its tempo from, in BPM. See *Beats* below. |
+| `immediate` | `boolean` | — | When `true`, fires one tick immediately (after ~1 ms) in addition to the normal schedule. |
+| `counter` | `number` | — | Overrides the internal trigger counter to a specific value. |
+| `running` | `boolean` | — | Setting to `false` stops the timer. Setting to `true` starts it if `start` is not otherwise specified. |
+| `until.triggerCount` | `number` | — | Automatically stops the timer after this many triggers have fired. |
+
+### Commands
+
+Commands are special keys that trigger immediate actions when passed to `configure`:
+
+| Command | Description |
+|---|---|
+| `start` | Starts the timer. Equivalent to sending `{ start: true }`. |
+| `stop` | Stops the timer and resets the counter to 0. |
+| `restart` | Stops the timer then immediately starts it again (equivalent to `stop` + `start`). |
+
+Changing `periodicValue` or `periodicUnit` while the timer is running silently restarts it with the new interval.
+
+---
+
+## Output Data
+
+Each tick emits a single object downstream:
+
+```json
+{ "triggerCount": 1 }
+```
+
+`triggerCount` starts at 1 and increments by 1 on every tick.
+
+---
+
+## Example: 1-second Periodic Timer
+
+The following Board Blueprint snippet configures a timer to fire once per second, starting immediately:
+
+```json
+{
+  "serviceId": "hookup.to/service/timer",
+  "config": {
+    "periodic": true,
+    "periodicValue": 1,
+    "periodicUnit": "s",
+    "immediate": true,
+    "start": true
+  }
+}
+```
+
+---
+
+## hkp-rt Differences
+
+The hkp-rt `timer` service uses a single `delay` property expressed in **microseconds** instead of the `periodicValue`/`periodicUnit` pair used by the browser runtime.
+
+| Browser Runtime | hkp-rt equivalent |
+|---|---|
+| `periodicValue: 1, periodicUnit: "s"` | `delay: 1000000` (1 second in µs) |
+| `periodicValue: 500, periodicUnit: "ms"` | `delay: 500000` |
+
+All other behaviour (counter, trigger output shape, `until.triggerCount`) is equivalent. Consult the hkp-rt source for the complete list of supported properties.

package/bundle/docs/content/services/tracks.md

@@ -0,0 +1,207 @@
+# Tracks
+
+Several pipelines over one input, and one answer out.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `tracks` |
+| Node.js (hkp-node) | `tracks` |
+| Python (hkp-python) | `tracks` |
+| C++ (hkp-rt) | `tracks` |
+
+---
+
+## What it does
+
+[Iterator](./iterator.md) runs one pipeline over many items. This is the other
+half of that pair: many pipelines over one item.
+
+```
+input ──┬── track ── answer ──┬── reduce ── output
+        ├── track ── answer ──┤
+        └── track ── answer ──┘
+```
+
+A board that has to do two unrelated things with the same value — write it to a
+table *and* tell somebody about it, ask three services and compare what they say
+— could always fake this by putting those things in a row and teaching each of
+them to pass its input through. That works, and records nothing: not that they
+are siblings rather than a sequence, not in which order they may run, not which
+of their answers matters. All three are this service's subject.
+
+**Every track is given the same input**, and no track can see another's answer.
+That is what lets a track be read on its own.
+
+---
+
+## The answers are an array, holes included
+
+One element per track, in declaration order. A track that stopped — declined,
+found nothing, failed — leaves `null` in its place rather than being left out,
+so position still names the track that produced it and a missing answer is
+visible rather than absent.
+
+An array of nothing but nulls is still an array. This service never stops a
+pipeline by itself; whether silence means stop is the reducer's to say:
+
+```json
+{ "=": "filter(params.results, 'item !== null').length ? params.results : null" }
+```
+
+That one is worth knowing, because tracks whose work is **asynchronous** answer
+nothing on the pass that feeds them — an aggregator collecting over an interval,
+a service that emits when a reply arrives. Their real output reaches the board
+later, by the same route any autonomous emitter's does: it leaves through this
+service and carries on down the pipeline. Without the reducer above, everything
+after this service is also handed a row of nulls on every pass.
+
+---
+
+## `run` — one at a time, or all at once
+
+```json
+{ "run": "serial" }
+```
+
+`serial` is the default and the safe one: two tracks writing to the same table
+are a race the moment they overlap, and concurrency should be asked for rather
+than discovered. `parallel` is for tracks that spend their time waiting on
+something else — an HTTP call, another runtime — where the waiting is the cost.
+
+Either way the answers come back in **declaration order**. How they ran is not
+something the next service should be able to tell.
+
+**Runtime differences:** the browser and hkp-node overlap tracks under
+`parallel`. hkp-python and hkp-rt process synchronously, so they record the
+setting and still run one track at a time — a board says the same thing and gets
+the same answers in every runtime; only the wall clock differs.
+
+---
+
+## `reduce` is a pipeline, not a list of strategies
+
+Taking the first answer, merging them, keeping only what came in: each is one
+`map` term, so there is nothing here to choose from and nothing to wait for
+somebody to add. The reducer is given both halves of what happened:
+
+```json
+{ "input": <what the tracks were run on>, "results": [ <answer>, … ] }
+```
+
+Carrying on as though the tracks were side effects — the commonest case, and the
+reason the reducer sees the input at all:
+
+```json
+{ "serviceId": "map", "state": { "mode": "replace", "template": { "=": "params.input" } } }
+```
+
+The first answer anything had: `{"=": "find(params.results, 'item !== null')"}`.
+Everything together under names the board chose: a template naming
+`params.results[0]`, `params.results[1]`. Something stranger: more services in
+the reduce pipeline, which is a pipeline like any other.
+
+With no reducer configured the array travels on as it is. **A reducer returning
+`null` stops the pipeline**, as any service does.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `tracks` | `Track[]` | `[]` | The pipelines, in the order their answers appear |
+| `reduce` | `PipelineEntry[]` | `[]` | Pipeline given `{ input, results }`; empty emits the array |
+| `run` | `"serial" \| "parallel"` | `"serial"` | One at a time, or together |
+| `bypass` | `boolean` | `false` | Passes the input straight through |
+
+A track is `{ "name": string, "bypass"?: boolean, "pipeline": PipelineEntry[] }`.
+The name is what a log, a panel and a reducer call it; a track without one is
+called by the position it was declared in. `reduce` is reserved — a track may
+not take it, since that is the name a pipeline edit uses to reach the reducer.
+A bypassed track leaves a hole, like one that stopped.
+
+---
+
+## Example
+
+Two writes about the same thing, and the thing itself carrying on:
+
+```json
+{
+  "uuid": "record-svc",
+  "serviceId": "tracks",
+  "serviceName": "Keep or drop",
+  "state": {
+    "run": "serial",
+    "tracks": [
+      { "name": "keep", "pipeline": [
+        { "instanceId": "insert", "serviceId": "sql", "serviceName": "Save an article",
+          "state": { "mode": "run", "statement": "INSERT INTO article (link) SELECT $link WHERE $intent = 'keep'" } }
+      ] },
+      { "name": "drop", "pipeline": [
+        { "instanceId": "delete", "serviceId": "sql", "serviceName": "Remove an article",
+          "state": { "mode": "run", "statement": "DELETE FROM article WHERE $intent = 'drop' AND link = $link" } }
+      ] }
+    ],
+    "reduce": [
+      { "instanceId": "carry", "serviceId": "map", "serviceName": "What came in",
+        "state": { "mode": "replace", "template": { "=": "params.input" } } }
+    ]
+  }
+}
+```
+
+Note what each half is for. The **guards stay in SQL**, because a condition about
+the data belongs in the language that addresses the data, and one guarded
+statement beats a filter and a statement. What the board gains is everything
+around them: that the two writes are independent, that they run in a known
+order, and that what leaves is the article rather than a count of changed rows.
+
+Demo board: `tracks-demo-board.json`.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value; every track is given it unchanged |
+| **Output** | The answers as an array, or whatever the reducer made of them |
+
+---
+
+## Addressing a service inside
+
+A service in a track, or in the reduce, is addressed through the Tracks holding
+it — `<tracks>.<instanceId>` — the way one inside a
+[SubService](./sub-service.md) is (see [Scopes](../concepts/scopes.md)). The
+track's name is not part of the address: an address runs through services, and
+a track is a pipeline of this one, so instance ids are unique across all of its
+tracks. A facade widget reads a request inside a track at that address, a
+notice watches it there, and a configure sent to it reaches the live service
+and is kept when the board is saved.
+
+In the browser, a facade whose `init` processes the Tracks waits until every
+track has been built, so a widget reading a service inside is listening before
+the first answer arrives.
+
+---
+
+## Replaces Stack
+
+The browser's `Stack` service was the first go at this idea: it fanned an input
+out to a list of sub-services and collected an array. It is gone, and boards
+carrying it have been rewritten. Three things changed.
+
+Its `output` setting was declared and never read, so there was no reduce at all.
+Its execution mode was welded to its input mode — `multiplex` ran serially,
+`lanes` ran everything at once — so neither could be chosen. And it existed only
+in the browser, so a board could not move.
+
+`lanes` is gone with it: it dealt element *i* of an incoming array to
+sub-service *i*, which reads as magic at the call site and is one `map` term at
+the start of a track — `{"=": "params[0]"}` — where it can be seen.