dirigent-examples 0.15.0__py3-none-any.whl

dirigent_examples/shelves/patterns/rule-one-failed.yaml

@@ -0,0 +1,86 @@
+# one_failed: the handler branch, drawn in the DAG instead of coded inside a block.
+#
+# one_failed fires when AT LEAST ONE prerequisite failed, and skips when none did. That is
+# what makes a step an error handler: it sits on the page next to the step it handles, so the
+# failure path is reviewable in a pull request rather than buried in an except clause.
+#
+# Hop by hop:
+#
+#   load      /status/${params.status}, 500 by default, so it fails.
+#   alert     one_failed on the load. It runs, and it is the only place the failure is
+#             described in words a human reads.
+#   carry_on  all_success on the load, the default. It is skipped, because the two branches
+#             are exclusive by construction: whichever way the load settles, exactly one of
+#             the pair runs and the other skips.
+#
+# EXPECT THIS RUN TO FAIL. The handler running is not a repair: the load is still red and
+# untolerated, so the run reports failed with the alert delivered. Pass -p status=200 and the
+# mirror image happens -- carry_on runs, alert skips, and the run succeeds.
+#
+# One sharp edge worth knowing before reaching for this: a step marked
+# continue_on_failure: true shows its dependents a success, so a one_failed handler hung below
+# a tolerated step never fires. Tolerating a failure and handling one are opposite
+# instructions.
+#
+#   dg run --local examples/patterns/rule-one-failed.yaml                 # fails; the alert branch runs
+#   dg run --local examples/patterns/rule-one-failed.yaml -p status=200   # succeeds; the alert skips
+
+format: dirigent/v1
+kind: pipeline
+code: rule-one-failed
+name: The one_failed edge
+description: |
+  `rule: one_failed` runs a step only when a prerequisite **failed**, and skips it when none
+  did. It is how an error-handling branch is drawn in the DAG.
+
+  As written the load fails, the alert branch runs, the success branch is skipped, and the
+  run reports `failed`.
+
+tags: [patterns, http, graph, rules]
+
+requires:
+  blocks:
+    - http.request
+
+params:
+  type: object
+  properties:
+    status:
+      type: integer
+      description: The status the load endpoint is asked to answer with; 500 fails, 200 does not.
+      default: 500
+      enum: [200, 500]
+
+steps:
+  load:
+    block: http.request
+    config:
+      url: "https://postman-echo.com/status/${params.status}"
+      method: GET
+
+  alert:
+    block: http.request
+    depends_on: [load]
+    # The whole file in one word. This step is unreachable on the happy path, and the graph
+    # says so without anything having to read a status code.
+    rule: one_failed
+    config:
+      url: https://postman-echo.com/post
+      method: POST
+      body:
+        text: the nightly load failed
+        # ${run.id} is what an operator pastes into dg runs show, so an alert carrying it is
+        # an alert somebody can act on.
+        run: "${run.id}"
+
+  carry_on:
+    block: http.request
+    depends_on: [load]
+    # The default rule, written out this once so the pair reads as a fork rather than as one
+    # step with an option on it.
+    rule: all_success
+    config:
+      url: https://postman-echo.com/post
+      method: POST
+      body:
+        text: the nightly load landed

dirigent_examples/shelves/patterns/schedule-at-once.yaml

@@ -0,0 +1,110 @@
+# The one-time clock: a single instant, agreed in advance and reviewable in a pull request.
+#
+# `at:` is the third clock, and it is the cutover and the launch: the migration that happens
+# once, at a moment somebody agreed to, that nobody should have to be awake for. Writing it in
+# the document rather than typing it into a terminal at two in the morning is the entire
+# argument for the field.
+#
+# HOW THE MOMENT IS READ, which is the part that goes wrong silently:
+#
+#   at: 2027-03-28 02:30:00   with timezone: Europe/Oslo   is half past two in Oslo. A naive
+#                             moment is anchored in the zone the schedule declares -- not in
+#                             UTC, and not in whatever the host's local time happens to be.
+#   at: 2027-03-28T02:30:00+01:00   is taken as given, and the timezone field is not consulted
+#                             at all. Write the offset yourself when you mean an instant.
+#
+# Exactly one clock per schedule. cron, interval and at are mutually exclusive, and a schedule
+# that declares none or two is refused when the document is parsed rather than at the moment
+# it should have fired.
+#
+# AFTERWARDS. Once the instant has gone by there is no next firing, so the schedule pauses
+# itself rather than disappearing: its parameters and its firing history stay readable with
+# dg schedule firings, which is what you want on the morning after a cutover.
+#
+# Hop by hop:
+#
+#   plan      turns the agreed bounds into the batches a migration would run.
+#   migrate   reads the plan and reports what it covered.
+#
+# EXPECT THIS RUN TO SUCCEED in about a second. The schedule fires only on an instance this
+# document has been applied to; locally the pipeline runs on its defaults.
+#
+# To change it: the pinned params below are the cutover's real bounds, and the pipeline's
+# defaults are a smaller rehearsal -- which is the shape to copy. Rehearse with dg run, and
+# let the schedule carry the real thing.
+#
+#   dg run --local examples/patterns/schedule-at-once.yaml
+#   dg run --local examples/patterns/schedule-at-once.yaml -p from=2025-01-01 -p to=2025-12-31
+#   dg apply examples/patterns/schedule-at-once.yaml
+#   dg schedule firings schedule-at-once cutover
+
+format: dirigent/v1
+kind: pipeline
+code: schedule-at-once
+name: One agreed instant
+description: |
+  `at:` fires once, at a single instant, and then pauses itself so its parameters and firing
+  history stay readable.
+
+  A moment written without an offset is anchored in the zone the schedule declares. Written
+  with one, it is taken as given and the zone is not consulted.
+
+tags: [patterns, transform, schedule]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    from:
+      type: string
+      format: date
+      description: First day of the migration window, inclusive.
+      default: "2026-01-01"
+    to:
+      type: string
+      format: date
+      description: Last day of the migration window, inclusive.
+      default: "2026-01-07"
+    environment:
+      type: string
+      enum: [staging, production]
+      default: staging
+
+steps:
+  plan:
+    block: transform.jq
+    config:
+      input:
+        from: "${params.from}"
+        to: "${params.to}"
+        environment: "${params.environment}"
+      program: |
+        {environment, from, to, batches: [range(1; 13)]}
+
+  migrate:
+    block: transform.jq
+    depends_on: [plan]
+    config:
+      input: "${steps.plan.output.value}"
+      program: |
+        {environment, migrated: "\(.from)..\(.to)", batches: (.batches | length)}
+
+triggers:
+  schedules:
+    - code: cutover
+      name: The agreed cutover
+      description: Runs the production migration once, at the moment operations agreed to.
+      # No offset, so this is half past four in the morning in Oslo, read through the zone
+      # below. It is also the night the clocks go forward, which is exactly the kind of date
+      # a naive moment plus a named zone gets right and a hand-computed UTC instant does not.
+      at: 2027-03-28 04:30:00
+      timezone: Europe/Oslo
+      # The real bounds live here, not in the pipeline's defaults: an ad hoc rehearsal should
+      # not accidentally be the cutover.
+      params:
+        from: "2025-01-01"
+        to: "2025-12-31"
+        environment: production

dirigent_examples/shelves/patterns/schedule-cron-timezone.yaml

@@ -0,0 +1,121 @@
+# A cron expression, and the zone that decides what it means.
+#
+# A cron field is five columns -- minute, hour, day of month, month, day of week -- and it
+# supports the whole ordinary vocabulary: * for every, a list (1,15), a range (1-5), a step
+# (*/15), and the two combined (0-23/2). The three schedules below use enough of it to read as
+# a reference.
+#
+# The zone is the load-bearing part, and it belongs to the SCHEDULE, not to the host the
+# scheduler happens to run on and not to the pipeline. That has one consequence worth stating
+# plainly: "0 5 * * *" in Europe/Oslo is five in the morning in Oslo all year, so it stays
+# five across a daylight-saving boundary rather than sliding to four or six. The same
+# expression in UTC never moves at all, and the difference between those two sentences is
+# exactly why the field exists.
+#
+# ONE PIPELINE, THREE CLOCKS. A schedule is not a second pipeline. The same document below is
+# fired at 05:00 Oslo for the nordics, at 05:00 Kathmandu for Nepal (a zone whose offset is not
+# a whole number of hours, which is a good reason never to hand-roll one), and on the first of
+# the month in UTC for the archive. Each pins its own parameters, which is what makes them
+# different runs of one thing rather than three copies of a document.
+#
+# The schedules exist only on an instance this document has been applied to. The pipeline
+# itself runs anywhere, and locally it takes the pipeline's defaults rather than any
+# schedule's pinned parameters.
+#
+# Hop by hop:
+#
+#   plan     turns the region and the day into the shape a loader would be handed.
+#   receipt  reads the plan back and reports what was covered.
+#
+# EXPECT THIS RUN TO SUCCEED in about a second, with no network and no allowlist.
+#
+# To change it: edit an expression and apply again -- an apply brings a managed schedule up to
+# date, and it never touches whether the schedule is paused, when it last fired, or the run
+# history. Those are facts about one instance, so they stay in it.
+#
+#   dg run --local examples/patterns/schedule-cron-timezone.yaml
+#   dg apply examples/patterns/schedule-cron-timezone.yaml
+#   dg schedule list schedule-cron-timezone
+
+format: dirigent/v1
+kind: pipeline
+code: schedule-cron-timezone
+name: Cron, in a named zone
+description: |
+  Five columns and the zone that decides what they mean. The timezone belongs to the
+  schedule, so `0 5 * * *` in `Europe/Oslo` is five in the morning in Oslo across a
+  daylight-saving boundary.
+
+  Three schedules on one pipeline, each pinning its own parameters: a schedule is not a
+  second pipeline.
+
+tags: [patterns, transform, schedule]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    region:
+      type: string
+      description: Which region the load covers; each schedule pins its own.
+      default: nordics
+    day:
+      type: string
+      format: date
+      description: The day being loaded.
+      default: "2026-01-01"
+
+steps:
+  plan:
+    block: transform.jq
+    config:
+      input:
+        region: "${params.region}"
+        day: "${params.day}"
+      program: |
+        {region, day, datasets: ["cases", "climate"]}
+
+  receipt:
+    block: transform.jq
+    depends_on: [plan]
+    config:
+      input: "${steps.plan.output.value}"
+      program: |
+        {covered: .region, day: .day, datasets: (.datasets | length)}
+
+triggers:
+  schedules:
+    - code: nordics-nightly
+      # A trigger carries the same quartet as anything else addressable: code addresses it,
+      # name and description only ever read.
+      name: Nightly, Oslo time
+      description: Fires once the upstream extract has settled for the day.
+      cron: "0 5 * * *"
+      timezone: Europe/Oslo
+      # Pinned parameters override the pipeline's defaults for this schedule's firings only.
+      params:
+        region: nordics
+        day: "2026-01-01"
+
+    - code: nepal-nightly
+      # Asia/Kathmandu is UTC+05:45. A named zone is the only honest way to write that, and
+      # the reason a schedule never takes a fixed offset.
+      cron: "0 5 * * *"
+      timezone: Asia/Kathmandu
+      params:
+        region: nepal
+        day: "2026-01-01"
+
+    - code: monthly-archive
+      # Day-of-month and month columns, and a minute that is not zero so two schedules that
+      # would otherwise collide on the hour do not. Every fifteen minutes would be */15 in
+      # the first column; every second hour, 0-23/2 in the second.
+      cron: "20 3 1 * *"
+      # UTC for a job with no human waiting on it: nothing about an archive is local.
+      timezone: UTC
+      params:
+        region: all
+        day: "2026-01-01"

dirigent_examples/shelves/patterns/schedule-interval.yaml

@@ -0,0 +1,109 @@
+# An interval: a cadence, not a calendar, and what happens when the scheduler was away.
+#
+# Write "every 1h" as an interval and "at 05:00 Oslo" as a cron, and neither has to fake the
+# other. An interval is right when what you want is freshness -- a poll, a rolling refresh, a
+# cache warm -- and nobody downstream cares which minute of the hour it lands on. A cron is
+# right when the firing is a calendar moment somebody expects.
+#
+# A duration is the same length in every zone, so an interval never consults a calendar: it
+# does not skip a day, it does not double one, and daylight saving is not a thing it can
+# notice. The timezone field is still there because a schedule carries one, and an interval
+# schedule simply does not read it.
+#
+# THE MISFIRE POLICY IS WHAT KEEPS AN HOURLY SCHEDULE FROM BECOMING A STORM. A firing late by
+# less than the grace (scheduler_misfire_grace, five minutes by default) is ordinary: the
+# clock advances from the slot it owed, so the cadence stays anchored where it was rather than
+# drifting by the length of a tick or by how long a run took. A firing late by MORE than the
+# grace is a misfire: it fires exactly once, and the next firing is computed from now,
+# abandoning every slot that was missed. So a scheduler down over a weekend wakes up and runs
+# this once, not sixty times. Backfilling the gap is a separate, deliberate act -- dg backfill
+# -- and not something a restart does to you.
+#
+# Hop by hop:
+#
+#   refresh  builds the rolling window the cadence implies, from a parameter rather than from
+#            the clock, so the same document runs identically ad hoc.
+#   report   reads it back and reports the coverage.
+#
+# EXPECT THIS RUN TO SUCCEED in about a second. Locally there is no scheduler, so the two
+# schedules below are declarations that travel with the document and nothing more.
+#
+# To change it: concurrency: skip is on this pipeline on purpose and belongs with the cadence.
+# Two firings of a rolling refresh are not worth having at once, and a refresh that takes
+# longer than its interval would otherwise stack runs until something gives.
+#
+#   dg run --local examples/patterns/schedule-interval.yaml
+#   dg apply examples/patterns/schedule-interval.yaml
+#   dg schedule list schedule-interval
+
+format: dirigent/v1
+kind: pipeline
+code: schedule-interval
+name: A rolling cadence
+description: |
+  An interval is a cadence rather than a calendar moment: a duration is the same length in
+  every zone, so nothing here consults a clock face.
+
+  A firing missed by more than the misfire grace fires **once** and re-anchors from now, so
+  a scheduler that was away for a weekend does not wake up and run sixty times.
+
+tags: [patterns, transform, schedule]
+
+# The cadence and the concurrency policy belong together: a refresh that runs longer than its
+# interval must not stack a second run on the first. concurrency-skip.yaml is what that
+# policy does in detail.
+concurrency: skip
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    window_hours:
+      type: integer
+      description: How much history each refresh re-reads; each schedule pins its own.
+      default: 24
+      minimum: 1
+      maximum: 168
+    environment:
+      type: string
+      enum: [staging, production]
+      default: staging
+
+steps:
+  refresh:
+    block: transform.jq
+    config:
+      input:
+        hours: "${params.window_hours}"
+        environment: "${params.environment}"
+      program: |
+        {environment, hours, buckets: [range(0; .hours; 6)]}
+
+  report:
+    block: transform.jq
+    depends_on: [refresh]
+    config:
+      input: "${steps.refresh.output.value}"
+      program: |
+        {environment, refreshed_hours: .hours, batches: (.buckets | length)}
+
+triggers:
+  schedules:
+    - code: hourly
+      name: Hourly refresh
+      # A humane duration, not a number of seconds. 90m and 1h30m are the same schedule.
+      interval: 1h
+      params:
+        window_hours: 24
+        environment: staging
+
+    - code: six-hourly-deep
+      # The same pipeline at a different cadence over a wider window is a second schedule,
+      # not a second pipeline.
+      interval: 6h
+      params:
+        window_hours: 168
+        environment: production

dirigent_examples/shelves/patterns/schedule-window-half-open.yaml

@@ -0,0 +1,105 @@
+# The interval a firing COVERS, and why both ends of it are written down.
+#
+# A schedule answers "when does this start". A window answers "what does this run cover", and
+# those are different questions: the nightly load at 05:00 is meant to read yesterday, not
+# this instant. Every schedule-fired run carries the interval that just closed, and a step
+# reads it exactly the way it reads a parameter: ${run.window.start} and ${run.window.end}.
+#
+# HALF-OPEN IS THE WHOLE POINT. start is included, end is excluded, so consecutive firings
+# tile the timeline with no overlap and no gap. A row observed exactly on a boundary belongs
+# to precisely one window. Writing the predicate out -- observed_at >= start and
+# observed_at < end -- is what makes that reviewable, and it is why both ends are in the query
+# rather than a single "day" the step has to interpret.
+#
+# THE WINDOW IS A PROPERTY OF THE RUN, NOT OF THIS DOCUMENT. Nothing below declares it; the
+# cadence computes it. So an ad hoc run has to be given one, and a run that carries no window
+# REFUSES the reference rather than resolving it to an empty string:
+#
+#   ${run.window.start} cannot be resolved: this run carries no window; a schedule-fired or
+#   backfilled run has one, and an ad hoc run only if it was started with one
+#
+# That refusal is a feature. Resolving to empty would silently widen the query to everything
+# the upstream system has, which is the failure nobody notices until the bill arrives.
+#
+# A window derived from a cron cadence is WALL-CLOCK, not a fixed number of hours. In
+# Europe/Oslo the spring-forward night is 23 hours long and the fall-back night is 25, and the
+# pair of instants says so honestly rather than rounding it away -- which is why the step
+# below computes its own duration from the two ends instead of assuming 86400 seconds.
+#
+# Hop by hop:
+#
+#   query    builds the extraction predicate from the two ends and the dataset.
+#   receipt  reads the predicate back and reports the coverage as one string.
+#
+# EXPECT A RUN WITH --window TO SUCCEED, and a run without one to FAIL at the first step with
+# the refusal quoted above. Both are worth doing once:
+#
+#   dg run --local examples/patterns/schedule-window-half-open.yaml --window 2026-06-01..2026-06-02
+#   dg run --local examples/patterns/schedule-window-half-open.yaml   # refused: no window
+#   dg apply examples/patterns/schedule-window-half-open.yaml
+#   dg backfill schedule-window-half-open --schedule nightly \
+#     --from 2026-06-01T05:00:00Z --to 2026-06-08T05:00:00Z --dry-run
+
+format: dirigent/v1
+kind: pipeline
+code: schedule-window-half-open
+name: The window a firing covers
+description: |
+  `${run.window.start}` and `${run.window.end}` are the interval a run covers: half-open, so
+  consecutive firings tile the timeline without overlapping or leaving a gap.
+
+  The window belongs to the run, not to this document. A run without one **refuses** the
+  reference rather than quietly widening the query to everything.
+
+tags: [patterns, transform, references, schedule]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    dataset:
+      type: string
+      description: Which dataset the extraction reads; the schedule pins it for every firing.
+      default: cases
+
+steps:
+  query:
+    block: transform.jq
+    config:
+      input:
+        dataset: "${params.dataset}"
+        # Both ends, as ISO 8601 instants. A reference that is the whole value stays typed,
+        # and these are strings, so they arrive as strings.
+        from: "${run.window.start}"
+        to: "${run.window.end}"
+      program: |
+        {
+          dataset,
+          from,
+          to,
+          predicate: "observed_at >= \(.from) and observed_at < \(.to)"
+        }
+
+  receipt:
+    block: transform.jq
+    depends_on: [query]
+    config:
+      input: "${steps.query.output.value}"
+      program: |
+        {loaded: .dataset, covering: "\(.from)..\(.to)"}
+
+triggers:
+  schedules:
+    - code: nightly
+      name: Nightly, Oslo time
+      description: Reads the day that closed at five this morning.
+      cron: "0 5 * * *"
+      # The zone is what makes the derived window a day of Oslo's clock rather than a fixed
+      # number of hours, so the daylight-saving nights come out right without anything in the
+      # steps knowing that daylight saving exists.
+      timezone: Europe/Oslo
+      params:
+        dataset: cases

dirigent_examples/shelves/patterns/sensor-http-ready.yaml

@@ -0,0 +1,121 @@
+# http.ready: waiting for a service to say it is up, without holding anything while you wait.
+#
+# A sensor observes and changes nothing. Each poke here is one short GET, "not yet" is the
+# EXPECTED answer rather than a failure, and between pokes the attempt is a parked row with a
+# wake-up time -- so waiting an hour for a service to come up costs a handful of rows and no
+# worker at all. That is the difference between this and a step that loops.
+#
+# The block's own config answers "what counts as ready":
+#
+#   expect_status  the statuses that mean ready. Empty means any 2xx, which is the sensible
+#                  default; a service that answers 204 when warm and 503 when not needs
+#                  nothing here, and one that answers 418 on purpose needs it named.
+#   contains       an optional body matcher. Readiness ALSO requires this text in the body, so
+#                  a load balancer answering 200 from a page that says "starting" is not ready.
+#   max_response   how much of the body is read while looking for it.
+#
+# The step's fields answer "how long, how often, and what if not":
+#
+#   poll           the cadence. Its default is a minute, which is right for a real service.
+#   deadline       when to give up. Its default is a day.
+#   on_timeout     fail (the default) or skip.
+#
+# WHY A NON-2xx IS NOT AN ERROR HERE, which is the thing to internalise: an http.request
+# against a 503 fails the step, because a request that was answered 503 did not do its job. An
+# http.ready against the same 503 has done its job perfectly -- it observed that the service is
+# not ready yet. Same status, same URL, opposite meanings, because one is an operator and the
+# other is a sensor.
+#
+# Hop by hop:
+#
+#   api_up     pokes an endpoint that answers 200 immediately, so it is ready on the first
+#              poke and the run does not wait at all. It also matches on the body, which is the
+#              guard that separates "the port is open" from "the service is up".
+#   smoke_test the ordinary call that was waiting for it, and the reason the sensor is here.
+#   report     reads the sensor's own output: which status made it ready, how long the poke
+#              took, and whether the body matcher was in play.
+#
+# EXPECT THIS RUN TO SUCCEED in about two seconds, with matched true.
+#
+# To change it: -p path=/status/503 never becomes ready, and after the deadline the step fails
+# -- with on_timeout: skip it would skip instead, which is timeout-skips-the-step.yaml.
+#
+#   dg run --local examples/patterns/sensor-http-ready.yaml
+#   dg run --local examples/patterns/sensor-http-ready.yaml -p path=/status/503   # fails at the deadline
+
+format: dirigent/v1
+kind: pipeline
+code: sensor-http-ready
+name: Waiting for a service
+description: |
+  `http.ready` pokes an endpoint until it answers ready. A non-2xx is "not yet", not an
+  error -- the same status that would fail an `http.request`.
+
+  `expect_status` and `contains` say what ready means; `poll`, `deadline` and `on_timeout`
+  are step fields and say how long you are willing to wait for it.
+
+tags: [patterns, http, sensor, transform]
+
+requires:
+  blocks:
+    - http.ready
+    - http.request
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    path:
+      type: string
+      description: The readiness path; /get answers 200 at once, /status/503 never answers ready.
+      default: /get
+    dataset:
+      type: string
+      description: Echoed by the endpoint, so the body matcher below has something to match on.
+      default: cases
+
+steps:
+  api_up:
+    block: http.ready
+    # Two seconds so the example is watchable. A real readiness check on a service that takes
+    # minutes to warm up polls in minutes: each poke is a scheduled row, and the cost of
+    # waiting is rows, not time.
+    poll: 2s
+    # Short for the same reason. The block's own default is a day, which is the right order of
+    # magnitude for "wait until somebody starts it".
+    deadline: 20s
+    config:
+      # A sensor names a target and nothing else: there is no method and no query map here,
+      # because looking is a GET and anything a look needs goes in the URL.
+      url: "https://postman-echo.com${params.path}?dataset=${params.dataset}"
+      # 200 only, rather than any 2xx. Naming it is what stops a 204 with an empty body from
+      # counting as a service that is serving.
+      expect_status: [200]
+      # The body matcher, and the reason it is worth having: a proxy in front of a starting
+      # service answers 200 from its own error page, and only the body tells them apart.
+      contains: "${params.dataset}"
+      max_response: 64kb
+
+  smoke_test:
+    block: http.request
+    depends_on: [api_up]
+    # The work that was waiting. Ordinary all_success, so it never runs against a service the
+    # sensor could not confirm.
+    config:
+      url: https://postman-echo.com/post
+      method: POST
+      body:
+        dataset: "${params.dataset}"
+
+  report:
+    block: transform.jq
+    depends_on: [smoke_test]
+    config:
+      input:
+        ready_status: "${steps.api_up.output.status}"
+        poke_ms: "${steps.api_up.output.duration_ms}"
+        # True when a contains matcher was configured, so a reader can tell a body-checked
+        # readiness from a status-only one.
+        matched: "${steps.api_up.output.matched}"
+      program: |
+        {ready_status, poke_ms, matched}