dirigent-examples 0.15.0__py3-none-any.whl

dirigent_examples/shelves/failure/step-timeout.yaml

@@ -0,0 +1,96 @@
+# A step that fails on time rather than on work, and the three clocks that could have done it.
+#
+# The step below asks for thirty seconds of sleep against a two-second budget. It is designed
+# to lose. The run fails in about two seconds, and the interesting part is which of the three
+# available clocks stopped it, because they are not interchangeable:
+#
+#   timeout   (a step field)  How long ONE block call may take before the engine abandons it.
+#                             This is the one that fires here.
+#   deadline  (a step field)  How long a step may keep WAITING on a sensor or a remote job.
+#                             A sensor's individual pokes are fast; what needs bounding is
+#                             the waiting between them. sensor-gate.yaml is that example.
+#   timeout   (block config)  The block's own limit on its own work -- here, when
+#                             shell.run kills the child process it started.
+#
+# The two on this step are set deliberately far apart. shell.run would let the process run for
+# 300 seconds by default, and the engine gives up after two, so the engine is what fails the
+# step. Widen the step's `timeout` past thirty and the sleep finishes and the step goes green;
+# narrow the block's own `timeout` below two and the block kills its own child first and
+# reports that instead. Same red step, different reason, and the error class in the attempt says which.
+#
+# A timeout is classified as a transient failure, which means a retry budget would spend
+# itself on it: three attempts against a sleep that is always too long is six seconds of
+# waiting and three identical failures. There is no retry here for exactly that reason -- a
+# deadline that cannot be met is not a flake.
+#
+# on_timeout decides what a timeout means. The default is fail, which is what this shows;
+# on_timeout: skip is the other answer, and it is what sensor-gate.yaml uses to let a run
+# carry on past a drop that never landed.
+#
+# This one uses shell.run, which executes code on the worker and is refused unless the
+# instance allowlists it: export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["shell.run"]', or pass
+# --enable-unsafe shell.run to a local run.
+#
+#   dg run --local examples/failure/step-timeout.yaml --enable-unsafe shell.run          # fails, in ~2s
+#   dg run --local examples/failure/step-timeout.yaml --enable-unsafe shell.run -p seconds=1  # succeeds
+
+format: dirigent/v1
+kind: pipeline
+code: step-timeout
+name: Step timeout
+description: |
+  A sleep that is asked to take thirty seconds, given two.
+
+  The run fails in about two seconds. It fails **on time, not on work**: the command was
+  healthy and would have finished, and the engine abandoned it anyway because the step
+  declared how long it was allowed to take.
+
+  Three clocks could stop a step, and they answer different questions:
+
+  | Field | Where it lives | What it bounds |
+  | --- | --- | --- |
+  | `timeout` | the step | one block call |
+  | `deadline` | the step | how long a sensor may keep waiting |
+  | `timeout` | the block's config | the block's own work |
+
+tags: [failure, execute, retry]
+
+requires:
+  blocks:
+    - shell.run
+
+params:
+  type: object
+  properties:
+    seconds:
+      type: integer
+      description: How long the command sleeps. Anything above the two-second budget loses.
+      default: 30
+      minimum: 0
+      maximum: 300
+
+steps:
+  start:
+    block: shell.run
+    config:
+      argv: [echo, "starting work that will not be allowed to finish"]
+
+  slow_work:
+    block: shell.run
+    depends_on: [start]
+    # The budget. The command below wants thirty seconds; it gets two, and the engine takes
+    # the attempt away from it.
+    timeout: 2s
+    config:
+      # 300 seconds is this block's own default, left as it is so the engine's clock is
+      # plainly the shorter one and plainly the one that fires.
+      timeout: 5m
+      command: "echo 'sleeping ${params.seconds}s'; sleep ${params.seconds}; echo 'never printed'"
+
+  # Skipped when the sleep is cut short, because the default all_success edge is not
+  # satisfied by a step the engine abandoned.
+  after:
+    block: shell.run
+    depends_on: [slow_work]
+    config:
+      argv: [echo, "only reached when the work fits in its budget"]

dirigent_examples/shelves/git/README.md

@@ -0,0 +1,32 @@
+# Git examples
+
+`git.checkout` puts an existing project into a run. It clones a repository at a ref into the
+run's work directory and reports the commit it landed on, so a `docker.build` names its context,
+a `docker.compose.up` names its compose file, and a transform names its files, all by a path
+relative to the checkout. [docs/git.md](../../docs/git.md) is the family's home.
+
+It is an **ordinary** block: it writes only under the run's work directory and reaches only the
+remote its connection names, so no id has to be allowlisted to run it.
+
+```bash
+dg run --local examples/git/git-checkout-public.yaml
+```
+
+The other two documents drive the `docker.*` family off a checkout, so they need a Docker
+daemon and the usual allowlist; each says so in its own header.
+
+Every document here carries its `git` connection in a `connections:` section, because a
+`--local` run has no instance to hold one. On a server the connection is created once and the
+document names it:
+
+```bash
+dg connection create git my-project --set url=https://github.com/owner/repo.git
+```
+
+## Pipelines
+
+| File | What it teaches |
+| --- | --- |
+| [git-checkout-public.yaml](git-checkout-public.yaml) | The block on its own: a public remote, a shallow checkout at the default branch, and the commit, ref, target and remote a downstream step reads. |
+| [git-checkout-build.yaml](git-checkout-build.yaml) | Starting an existing project: the repository's own Dockerfile built from the checkout, and the image run once to prove it starts. |
+| [git-checkout-compose.yaml](git-checkout-compose.yaml) | A stack from somebody else's compose file: the checkout is what puts it where the compose CLI can open it, and the docker family's up/drive/down lifecycle is unchanged. |

dirigent_examples/shelves/git/git-checkout-build.yaml

@@ -0,0 +1,125 @@
+# Starting an existing project: check the repository out, build its Dockerfile, run the image.
+#
+# This is the answer to "I have a project on GitHub, how do I get it into a pipeline". Nothing
+# is copied by hand and no Dockerfile is written into the document: the repository's own build
+# is what runs.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev), and network from the worker to github.com.
+# docker.build and docker.run declare local_execution, so the engine refuses them unless the
+# instance allowlists their ids -- git.checkout is ordinary and needs no allowlisting:
+#   dg run --local examples/git/git-checkout-build.yaml --enable-unsafe docker.run,docker.build
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.run","docker.build"]'
+#
+# Three hops, and what each one hands on:
+#   source  the repository, shallow, into source/ in the run's work directory. Output: the
+#           commit, and the path the build step names next.
+#   build   buildx builds that directory with the repository's own Dockerfile and loads the
+#           image into the worker's daemon store. Output: the image id, its size and its tags.
+#   smoke   the built image, run once, proving the project starts.
+#
+# THE CHECKOUT IS WHAT MAKES THE BUILD POSSIBLE. docker.build takes a context DIRECTORY on the
+# worker's filesystem and has no inline form, so before this block existed a pipeline had to
+# put every file there itself, one storage.copy at a time. A checkout puts a whole repository
+# there in one step, and the build names it by the same work-directory-relative path the
+# checkout reported.
+#
+# THE TAG IS THE CONTRACT. Nothing is pushed anywhere, so the image exists only in the store of
+# the daemon that built it, under the tag the build gave it. Both steps read that name from one
+# parameter, and both must land on the same docker-capable worker: an image built on worker A
+# is invisible to worker B, which is what requires.workers below routes around.
+#
+# WHY THE RUN STEP OVERRIDES THE COMMAND. The image's own CMD starts an HTTP server and never
+# returns, and a step has to end. So the smoke step starts the project's server, asks it for a
+# page, and exits with whether it answered -- which is what "it builds and it runs" means for
+# a service. Running a stack that stays up for the rest of a run is the compose example's job.
+#
+# TO MAKE IT YOURS: point the connection at your own repository, pin a ref: to a tag or a
+# commit rather than tracking a branch, and replace the smoke step with your project's own
+# check -- its test suite, its migration, its one-shot job.
+
+format: dirigent/v1
+kind: pipeline
+code: git-checkout-build
+name: Build a checked-out project
+description: Check a public repository out, build the Dockerfile it ships, and run the image once.
+
+tags: [git, execute]
+
+requires:
+  blocks:
+    - git.checkout
+    - docker.build
+    - docker.run
+  workers:
+    - docker
+
+connections:
+  helloworld-demo-node:
+    kind: git
+    config:
+      # Docker's own sample project: a Node server with no dependencies and a Dockerfile at
+      # the repository root, which is the shape docker.build expects by default.
+      url: https://github.com/dockersamples/helloworld-demo-node.git
+
+params:
+  type: object
+  additionalProperties: false
+  properties:
+    image_tag:
+      type: string
+      default: dirigent-helloworld:local
+      description: The tag the build gives the image, and the only name the smoke step has for it.
+
+steps:
+  source:
+    block: git.checkout
+    deadline: 5m
+    config:
+      connection: helloworld-demo-node
+      # Named rather than defaulted, so the build step below can say "source" out loud instead
+      # of depending on what this step happens to be called.
+      target: source
+      depth: 1
+
+  build:
+    block: docker.build
+    depends_on: [source]
+    deadline: 15m
+    config:
+      # The checkout's directory, relative to the run's work directory. The Dockerfile path is
+      # relative to it, and
+      # "Dockerfile" is already the default; it is written out here because the whole point is
+      # that this is the repository's file and not one this pipeline invented.
+      context: source
+      dockerfile: Dockerfile
+      tags: ["${params.image_tag}"]
+      # The Dockerfile's npm ci runs inside the build, so the build needs the network the
+      # daemon has; nothing else about it is dirigent's business.
+      pull: true
+
+  smoke:
+    block: docker.run
+    depends_on: [build]
+    deadline: 5m
+    config:
+      image: "${params.image_tag}"
+      # pull stays off, and must: the image was never pushed, so a pull would look for this
+      # tag in a registry and fail on a name the daemon already holds locally.
+      pull: false
+      # none, not bridge: the server and the request that proves it are both in this
+      # container, so the loopback interface is the whole network this step needs.
+      network: none
+      # The shell form, because this is a small script rather than one command: start the
+      # project's server in the background, then ask it for a page until it answers. Ten
+      # tries at a second apart is generous for a process that binds a port and nothing else.
+      command: |
+        node app.js &
+        for _ in 1 2 3 4 5 6 7 8 9 10; do
+          wget -qO- http://127.0.0.1:8080/ && exit 0
+          sleep 1
+        done
+        echo "the server never answered" >&2
+        exit 1
+      memory: 256mb
+      pids_limit: 128

dirigent_examples/shelves/git/git-checkout-compose.yaml

@@ -0,0 +1,138 @@
+# A stack brought up from a compose file that lives in someone else's repository.
+#
+# The compose file is not in this document and was not written into the work directory by an
+# earlier
+# step: it is a file in a public repository, and the checkout is what puts it somewhere the
+# compose CLI can open.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev), and network from the worker to github.com. The three
+# docker blocks declare local_execution, so the engine refuses them unless the instance
+# allowlists their ids -- git.checkout is ordinary and needs no allowlisting:
+#   dg run --local examples/git/git-checkout-compose.yaml \
+#     --enable-unsafe docker.compose.up,docker.compose.down,docker.run
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up","docker.compose.down","docker.run"]'
+#
+# Four hops, and what each one hands on:
+#   source    the repository, shallow, into source/ in the run's work directory. Output: the
+#             commit and the target the compose step names a file inside.
+#   stack     compose brought up from that file, detached, and left running for the rest of
+#             the run. Output: the services, the networks, and default_network.
+#   probe     a container on the stack's network, asking the service for a page.
+#   teardown  the same project down again, volumes included, on any outcome.
+#
+# THE PATH IS WORK-DIRECTORY-RELATIVE ALL THE WAY THROUGH. docker.compose.up names a file
+# inside the run's work directory, never an absolute path and never one that climbs out, and
+# the checkout landed the whole repository at "source". So the compose file is
+# "source/<directory>/compose.yaml" -- the repository's own layout, prefixed by where the
+# checkout put it. The CLI is always run with --project-directory set to the work directory,
+# so a compose file with relative paths of its own resolves them against the run's directory
+# rather than its own: a stack of pre-built images, like this one, is what that suits.
+#
+# PIN THE REF FOR ANYTHING REAL. This one tracks the repository's default branch, which is
+# honest for an example and wrong for a pipeline you rely on: somebody else's commit would
+# change what your stack is. A ref: naming a tag or a full commit sha is how a checkout stops
+# being a moving target, and the commit output is what to record when it is not.
+#
+# THE LIFECYCLE IS THE DOCKER FAMILY'S, UNCHANGED. up brings the stack up and it persists, a
+# step drives it, and a down with rule: all_done tears it down whether the drive step passed
+# or failed. Both compose steps default their project name from the run id, so the down
+# addresses exactly the project the up created with nothing wired between them.
+#
+# TO MAKE IT YOURS: point the connection at the repository whose stack you actually run, name
+# its compose file under compose_path, and replace the probe with something that proves your
+# services are up -- a request that must return 200, a query that must return rows.
+
+format: dirigent/v1
+kind: pipeline
+code: git-checkout-compose
+name: A stack from a repository's compose file
+description: Check a repository out, bring up the compose file it ships, probe it, and tear it down.
+
+tags: [git, execute]
+
+requires:
+  blocks:
+    - git.checkout
+    - docker.compose.up
+    - docker.compose.down
+    - docker.run
+
+connections:
+  awesome-compose:
+    kind: git
+    config:
+      # Docker's own collection of sample stacks. It is public, so no credential is sealed
+      # here; a private repository would carry a token or a deploy key on this connection and
+      # the steps below would not change at all.
+      url: https://github.com/docker/awesome-compose.git
+
+params:
+  type: object
+  additionalProperties: false
+  properties:
+    compose_path:
+      type: string
+      default: source/wordpress-mysql/compose.yaml
+      description: The compose file to bring up, as a path under the run's work directory.
+
+steps:
+  source:
+    block: git.checkout
+    deadline: 10m
+    config:
+      connection: awesome-compose
+      target: source
+      # One commit and none of its history: this pipeline reads two files out of the tree and
+      # has no use for the years of log behind them.
+      depth: 1
+
+  stack:
+    block: docker.compose.up
+    depends_on: [source]
+    deadline: 15m
+    config:
+      # A file, not content: this is the form for a compose document something else produced,
+      # and a checkout is the most direct producer there is.
+      file: "${params.compose_path}"
+      # The stack's services declare no healthcheck, so --wait can only wait for their
+      # containers to be running; the probe below is what waits for the application itself.
+      wait: true
+      wait_timeout: 5m
+      pull: always
+
+  probe:
+    block: docker.run
+    depends_on: [stack]
+    deadline: 10m
+    config:
+      image: alpine:3
+      pull: true
+      # The network the up step reported: joining it resolves the service by the name the
+      # compose file gave it.
+      network: "${steps.stack.output.default_network}"
+      # The web service answers seconds after its container is running, and only once the
+      # database behind it does, so the probe retries rather than racing it. This is what a
+      # stack without a healthcheck costs the step that drives it.
+      command: |
+        for _ in $(seq 1 90); do
+          wget -q --spider http://wordpress/ && exit 0
+          sleep 2
+        done
+        echo "the service never answered" >&2
+        exit 1
+      memory: 64mb
+      pids_limit: 64
+
+  teardown:
+    block: docker.compose.down
+    depends_on: [probe]
+    # all_done runs the teardown on success or failure, so the stack never outlives the run.
+    rule: all_done
+    deadline: 10m
+    config:
+      # The same file the up step used, passed back from its output: a teardown resolves the
+      # project by label alone in most cases, and needs -f in the ones where it cannot.
+      file: "${steps.stack.output.compose_file}"
+      # The stack's named volumes go with it, so a run leaves nothing on the worker.
+      down_volumes: true

dirigent_examples/shelves/git/git-checkout-public.yaml

@@ -0,0 +1,84 @@
+# A public repository checked out into the run's work directory, and the commit it landed on.
+#
+# NEEDS NETWORK from the worker to github.com, and nothing else: git.checkout is an ordinary
+# block, so no id has to be allowlisted and no daemon has to be reachable.
+#   dg run --local examples/git/git-checkout-public.yaml
+# docs/git.md is the family's home.
+#
+# Two hops, and what each one hands on:
+#   checkout  the repository, shallow, at its default branch, at checkout/ in the run's
+#             work directory.
+#             Output: commit, ref, target and remote.
+#   report    a constant step that reads those three fields, which is all it takes to prove
+#             they are references any downstream step can name.
+#
+# THE CONNECTION HOLDS THE REMOTE, THE DOCUMENT HOLDS THE REF. A checkout step never writes a
+# URL: it names a git connection, and the connection is what carries the remote and, when the
+# repository is private, the sealed token or deploy key that reaches it. Moving a pipeline
+# from a fork to the real repository is then an edit to one connection and to no pipeline.
+# This one is carried in the document because a --local run has no instance to hold it; on a
+# server it would be created once, with `dg connection create git ...`, and the document would
+# name it and stop there. Public repositories need no credential at all, which is why there is
+# none here.
+#
+# WHERE IT LANDS. target is a path inside the run's work directory -- never absolute, never
+# climbing out -- and left unset it is the step's own name, so this checkout is at
+# checkout/. A checkout is a directory a tool opens rather than bytes in storage, which is
+# why it lands there and not under ${run.scratch}. That relative path is the whole point of
+# the block: a downstream docker.build names it as a context, a docker.compose.up names a
+# file inside it, and a transform names its files, none of them knowing where the run's work
+# directory actually is.
+#
+# SHALLOW BY DEFAULT. depth is 1 unless a document says otherwise, which fetches the one
+# commit the ref points at and none of its history. That is what a build wants and it is a
+# fraction of the bytes. Set depth: 0 for the whole history, which is what a step that reads
+# the log or runs `git describe` needs.
+#
+# TO MAKE IT YOURS: point the connection at your own repository, add a ref: if the default
+# branch is not what you want, and replace the report step with whatever actually reads the
+# checkout.
+
+format: dirigent/v1
+kind: pipeline
+code: git-checkout-public
+name: Check a public repository out
+description: Clone a public repository at its default branch into the run's work directory and report the commit.
+
+tags: [git]
+
+requires:
+  blocks:
+    - git.checkout
+    - value.const
+
+connections:
+  octocat-hello-world:
+    kind: git
+    config:
+      # GitHub's own smallest repository: one README and two commits. Nothing is sealed here
+      # because nothing needs to be -- a public remote takes no credential.
+      url: https://github.com/octocat/Hello-World.git
+
+steps:
+  checkout:
+    block: git.checkout
+    deadline: 5m
+    config:
+      connection: octocat-hello-world
+      # No ref, so the remote's own default branch is what lands, and the output reports which
+      # one that turned out to be.
+      depth: 1
+
+  report:
+    block: value.const
+    depends_on: [checkout]
+    config:
+      # The commit is the only exact name for what was checked out: a branch moves, a tag can
+      # be moved, and a sha cannot. A step that records what a pipeline built records this.
+      value:
+        commit: "${steps.checkout.output.commit}"
+        ref: "${steps.checkout.output.ref}"
+        # The remote as the output reports it, which is the URL with any credential stripped.
+        remote: "${steps.checkout.output.remote}"
+        # Relative to the run's work directory, which is the form every downstream block wants.
+        target: "${steps.checkout.output.target}"

dirigent_examples/shelves/graph/README.md

@@ -0,0 +1,22 @@
+# Graph examples
+
+The shapes a DAG takes: a straight line, branches that split and join, a fan over a list,
+and a chain deep enough to watch the engine walk it. Every one runs with `dg run --local`,
+and the ones that call out use only Postman Echo.
+
+```bash
+dg run --local examples/graph/linear.yaml -p day=2026-01-01 --enable-unsafe shell.run
+```
+
+## Pipelines
+
+| File | What it teaches |
+| --- | --- |
+| [linear.yaml](linear.yaml) | The straight line: fetch, archive, report, each step reading the one before it. |
+| [parallel-branches.yaml](parallel-branches.yaml) | Two branches from one root, joined by a step that reads both. |
+| [fan-out.yaml](fan-out.yaml) | `for_each` over a list: one item per region, and a refusal that fails the item rather than the fan. |
+| [fan-in.yaml](fan-in.yaml) | The other direction: parallel fetches whose whole fan one step reads back as a list. |
+| [wide-fan.yaml](wide-fan.yaml) | A fan wide enough to fill every worker slot, for watching concurrency rather than reading about it. |
+| [deep-chain.yaml](deep-chain.yaml) | Ten steps in one line, each reading the one above it. |
+| [skip-diamond.yaml](skip-diamond.yaml) | A diamond where one road is taken and the other settles as skipped, not failed. |
+| [parallel-sleep.yaml](parallel-sleep.yaml) | Three independent waits at once, and the join that waits for all of them. |

dirigent_examples/shelves/graph/deep-chain.yaml

@@ -0,0 +1,119 @@
+# Graph height: ten steps in a single file, where every one waits for the one before it.
+#
+# This document exists to be looked at rather than to compute anything. Height is the length
+# of a DAG's longest path, and it is the one dimension no amount of hardware shortens: each
+# step here reads the step above it, so the tenth cannot start until the ninth has settled.
+# Ten workers finish this run no faster than one does.
+#
+# wide-fan.yaml is the same idea turned ninety degrees -- ten steps that are all claimable at
+# once. Run both and watch the graph: this one draws a column, that one draws a row. Between
+# them they are the two numbers worth knowing about a pipeline's shape, because height is
+# what sets the floor on a run's duration and width is what sets the demand on the workers.
+#
+# The value threaded down the chain is a running total, so each step's output visibly depends
+# on its predecessor's rather than merely coming after it in the drawing. transform.jq opens
+# no socket and runs nothing on the worker, so the whole column needs no allowlist entry and
+# no network.
+#
+#   dg run --local examples/graph/deep-chain.yaml
+#   dg run --local examples/graph/deep-chain.yaml -p start=100
+
+format: dirigent/v1
+kind: pipeline
+code: deep-chain
+name: Deep chain
+description: |
+  Ten steps in one line, each reading the one above it.
+
+  The longest path through a DAG is its **height**, and it is the floor under the run's
+  duration: no number of workers makes a chain shorter. Its opposite is
+  `wide-fan`, where all ten steps are claimable at once.
+
+tags: [graph, transform]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    start:
+      type: integer
+      description: What the first link adds to.
+      default: 0
+
+steps:
+  # The first link is the only one with no depends_on, so it is the only root: the run has
+  # exactly one claimable step at the moment it is created, and never more than one after.
+  link_1:
+    block: transform.jq
+    config:
+      input:
+        total: "${params.start}"
+      program: "{total: (.total + 1), depth: 1}"
+
+  link_2:
+    block: transform.jq
+    depends_on: [link_1]
+    config:
+      input: "${steps.link_1.output.value}"
+      program: "{total: (.total + 2), depth: 2}"
+
+  link_3:
+    block: transform.jq
+    depends_on: [link_2]
+    config:
+      input: "${steps.link_2.output.value}"
+      program: "{total: (.total + 3), depth: 3}"
+
+  link_4:
+    block: transform.jq
+    depends_on: [link_3]
+    config:
+      input: "${steps.link_3.output.value}"
+      program: "{total: (.total + 4), depth: 4}"
+
+  link_5:
+    block: transform.jq
+    depends_on: [link_4]
+    config:
+      input: "${steps.link_4.output.value}"
+      program: "{total: (.total + 5), depth: 5}"
+
+  link_6:
+    block: transform.jq
+    depends_on: [link_5]
+    config:
+      input: "${steps.link_5.output.value}"
+      program: "{total: (.total + 6), depth: 6}"
+
+  link_7:
+    block: transform.jq
+    depends_on: [link_6]
+    config:
+      input: "${steps.link_6.output.value}"
+      program: "{total: (.total + 7), depth: 7}"
+
+  link_8:
+    block: transform.jq
+    depends_on: [link_7]
+    config:
+      input: "${steps.link_7.output.value}"
+      program: "{total: (.total + 8), depth: 8}"
+
+  link_9:
+    block: transform.jq
+    depends_on: [link_8]
+    config:
+      input: "${steps.link_8.output.value}"
+      program: "{total: (.total + 9), depth: 9}"
+
+  # The last link reports the height it sits at alongside the total, so the run's output says
+  # what the drawing says.
+  link_10:
+    block: transform.jq
+    depends_on: [link_9]
+    config:
+      input: "${steps.link_9.output.value}"
+      program: "{total: (.total + 10), depth: 10, note: \"55 added over ten dependent steps\"}"