Docs

Steps & guarantees

How steps map to Dot capabilities and how guarantees are enforced.

Steps describe what the job does in terms of Dot capabilities, not vendor APIs. The user's Dot decides how to carry each step out with the apps it has connected. Guarantees are promises the runtime checks on every run.

Steps

steps

steps:
  - id: fetch                       # unique within the job; later steps reference it by id
    do: web.fetch(inputs.listing_urls)
  - id: diff
    do: diff_against_previous(fetch)
    parallel: false                 # default; set true when items are independent
  - id: notify
    do: telegram.send(inputs.deliver_to, summarise(diff))
    safe: true                      # eligible for "auto-apply safe fixes" approval mode
    when: diff.changed              # skip unless the condition holds

Property	Required	Meaning
`id`	yes	Reference name for outputs and later steps.
`do`	yes	A capability call. Arguments may reference inputs.* and earlier step ids.
`parallel`	no	Run the capability per item concurrently when the input is a list.
`safe`	no	Marks a writing step as safe to auto-apply. Defaults to false for writes.
`when`	no	Boolean expression over earlier results. Step is skipped when false.
`retry`	no	Attempts and backoff for flaky sources, e.g. { attempts: 3, backoff: 30s }.

Capabilities

A capability is something a Dot can do. Generic capabilities work across apps; app-scoped ones use the prefix of an app in connects.

Capability	Kind	Example
`web.fetch`	read	Fetch pages, follow pagination, respect robots.
`diff_against_previous`	compute	Compare with the last run's snapshot.
`gather_public_data`	read	Research entities across public sources with citations.
`summarise / cluster / score_against`	compute	Language and ranking steps with no side effects.
`sheets.write · notion.upsert · github.open_pr`	write	Destination writes; always logged and reversible.
`slack.send · telegram.send · email.send`	write	Messages; rollback posts a correction.
`chain.subscribe · chain.decode · chain.price`	read	On-chain reads across supported networks. Never signs.

Guarantees

Guarantees are declared in the package and enforced by the runtime: a run that would violate one fails before anything is written. They are also shown on the listing, so users know what to expect.

Guarantee	What the runtime checks
`read_only`	No write capability is called. Required for all crypto jobs in the catalogue.
`no_writes_outside_destination`	Every write targets a declared output.
`every_field_has_source`	Each produced field carries at least one source link.
`no_outbound_messages`	No messages are sent to third parties (only to the user's own channels).
`idempotent`	Running twice with the same inputs produces no additional writes.
`max_runtime: 30m`	The run is cancelled, with nothing written, past the limit.

Writing good steps

Keep reads, computes and writes as separate steps so approval previews are precise.
Mark a step safe: true only if undoing it is trivial and it is never customer-facing.
Prefer one destination per job. Multiple destinations are allowed but make rollback noisier.
Use when to avoid empty deliveries — a monitor that found nothing should stay quiet.