A machine names which argument a source feeds: (path, benchmark=bench) -> compare -> result
binds bench to the argument named benchmark. Members without a name are matched by type as
before, and only a real ambiguity is refused, naming the members to name.
A member can be a constant: (prices, window=20, statistic="mean") -> rolling -> smooth. A
constant satisfies the argument’s own validation, and a run cannot give an argument a constant
binds another value.
A machine can start from constants alone, (reference="fred/UNRATE") -> fetch -> series, or
from nothing, () -> now -> stamp, and can end in a sink, report -> publish -> ().
A step can give several outputs, each with a name: obs -> regress -> (fit, residuals=res). The
unnamed one is the cap’s main output. An output a cap declares optional may not fire; what
needs it is then skipped, and a machine output that was not produced is reported as not
produced, which is not the same as empty.
Several sequences into one step’s single-valued arguments are zipped: item i of each runs
together, and sequences of different lengths are an error naming them. A sequence produced
inside a map can be mapped again; the results flatten, in order.
A machine can use another machine as a step: [clean machine "clean.machine"] in the header,
wired by the included machine’s input and output names. A machine that includes itself, however
indirectly, is refused.
A step can say how it fails: fetch{retry=3} retries a failure that may pass on a second
attempt (resources, the environment, an internal fault), never one of the input’s or the
user’s; parse{on_error=absent} lets the run go on without that step’s outputs. A run that
went on past tolerated failures completes saying so.
Steps with no path between them run at the same time, within the limits the hosts already
impose. Results are in item and binding order, whichever step finished first.
true, false and null cannot be node names.
Cap definitions
Every argument and every output of a cap has a name, required and unique within the cap. It is a
label: an argument and an output are still identified by their media URN, and nothing is
assumed from a name about a URN.
A cap’s outputs are a list, outputs, with exactly one main output. An output can be optional,
and can carry its cap’s input type unchanged. An argument can declare accepts, the type its
stream takes when that is not its own URN, so two arguments can take one type.
The definition rules are held by every reader: a cartridge whose manifest declares a definition
that breaks a rule is not attached, and a registry with such a definition is refused, naming the
cartridge and the rule.
The plan types no longer have Merge and Split nodes or JsonField and JsonPath edges;
nothing produced them. ConvergenceMechanism::Merge is Product.
The wire protocol
Hosts and cartridges speak protocol version 5. A response has one stream per output its cap
declares, and each stream other than the main output’s names the output it carries. A required
output the handler never wrote to is sent empty; an optional one is not sent.
A peer call’s response gives the main output’s items and each other output’s items apart, so a
caller that wants only the answer reads it without the rest.
The capdag command
A machine’s inputs are given by the names its notation gives them: --input <node>=<value>,
with @<path> reading a file. A path given without a name goes to the input its type fits; a
machine with one input given several paths runs once per path.
Files a run writes are named after the output’s name in the notation:
{input}.{node}[.{i}].{ext}. An output the run did not produce is said, not written.
The exit status says how a run ended: 0 completed, 3 completed with failures a step’s policy
tolerated (listed on stderr), 1 failed, 130 cancelled.
Media types
An image, audio, a video and a document are each a type of their own: media:image,
media:audio, media:video, media:document. Every format of a medium conforms to it, so
media:ext=png;image is a media:image. media:image and media:audio used to be tags with
no type behind them.
A PDF is media:document;ext=pdf, and the other document formats (docx, epub, xlsx, pptx and
the rest) carry document the same way. They were media:ext=pdf and so on, with nothing to
say what they have in common. A cap, a machine or a script that names media:ext=pdf names a
type that no longer exists.
Raw audio frames are media:audio;audio-frames;pcm: audio, like the files they are encoded to.
The libraries’ MEDIA_IMAGE, MEDIA_AUDIO, MEDIA_VIDEO and MEDIA_DOCUMENT are the four
mediums, in all five languages. MEDIA_AUDIO used to be WAV under a second name, and
MediaImage in Go and Objective-C was PNG; MEDIA_WAV and MEDIA_PNG are those formats.
Capabilities
convert-image is declared image to image and convert-audio audio to audio. Both were
declared media: to media:: a claim to convert anything, over converters that only take and
make one medium. capdag convert-image note.txt --to png is refused as before, and the refusal
now shows the type the cap declares.
disbind takes a document.
extract-frames and extract-audio-track name the per-container extractors by one alias each:
capdag extract-frames clip.mkv runs the MKV extractor, capdag extract-audio-track clip.mp4
the MP4 one.
A cap’s documentation links to other caps and types by the names the registry holds. Twenty
links pointed at spellings the registry had dropped and opened on “not found”.
Scaffolded cartridges
A Rust cartridge made by capdag new --rust builds with
cargo build --release --target-dir target. Its entry is declared as
target/release/<name>, and plain cargo build --release puts it there only
under a cargo that builds beside the sources; under one that keeps build
output elsewhere, the documented command built the cartridge and left no
entry for capdag dev-install to find.
The capdag command
capdag self update replaces the bundle — the executable and its bundled-cartridges/ — with
the latest release of its channel, where the bundle is. It installs a release only when the
release manifest’s signature chains to the keys built into the capdag you run, the bundle has
the size and SHA-256 digest the manifest lists, and the executable in it reports the version it
was published as. An update that is interrupted leaves a bundle that runs.
A capdag installed by Homebrew, apt or dnf is not replaced by capdag self update: it says
what updates it. The packages mark the bundle they install with a file named installed-by
beside the executable.
The registry
An abstract cap is published only if it names the medium its specializations share, and a
definition only if every link in its documentation resolves. Both are checked with the rest of
the catalogue.