dirigent-examples 0.15.0__py3-none-any.whl

dirigent_examples/shelves/open-data/wikidata-country-reference.yaml

@@ -0,0 +1,146 @@
+# The country code table every integration ends up needing, built from Wikidata rather than typed.
+#
+# Wikidata's SPARQL endpoint is public and keyless. It answers SPARQL over the whole of
+# Wikidata, and with `Accept: application/sparql-results+json` the answer is the W3C results
+# shape: {"head": {"vars": [...]}, "results": {"bindings": [...]}}, where every binding is a
+# map from variable name to {"type": ..., "value": ...} -- and every value is a *string*, even
+# the numeric ones. Unwrapping that envelope is most of the work below.
+#
+# The query asks for sovereign states with an ISO 3166-1 alpha-3 code, plus the alpha-2 and
+# numeric codes and the English label. The result is the reference table other pipelines join
+# against: WHO GHO speaks alpha-3, health information systems often carry alpha-2, and national statistics
+# offices publish the numeric code.
+#
+# On manners: the endpoint asks every client for a descriptive User-Agent that says who is
+# calling and how to reach them, and it will refuse an anonymous one under load. That header is
+# not optional politeness, it is the terms of use. A query heavier than this one belongs behind
+# a longer timeout, or in the Query Service's own bulk export.
+#
+# What happens, hop by hop:
+#
+#   fetch     one GET with the query in the `query` parameter and the answer negotiated to
+#             JSON by the Accept header.
+#   table     the unwrapping: `.results.bindings` mapped to flat rows, each `.value` pulled
+#             out of its little envelope, the numeric code turned into an actual number, and
+#             the Wikidata entity URI cut down to its Q-id.
+#   publish   storage.write, the table as json. A reference table is a thing other runs read
+#             rather than a value this run carries onward, and a value leaves the run here.
+#   recalled  storage.read of that object: the read another pipeline would do against the same
+#             path, which is the only way a value comes back in.
+#   summary   what the run reports, counted off what came back rather than off what was held
+#             in memory upstream.
+#
+# To make it yours: change the query. Swapping wd:Q3624078 for wd:Q6256 widens it from
+# sovereign states to countries, and adding `?item wdt:P1082 ?population` gives every row a
+# population without another request. The table is written into the run's own scratch, which is
+# deleted with the run; on an instance, writing to s3:// or to a stable prefix is what makes the
+# table outlive the run that built it. A reference is not a parameter with a default, because a
+# parameter default is literal text: ${run.scratch} means nothing until a step resolves it.
+#
+#   dg run --local examples/open-data/wikidata-country-reference.yaml
+
+format: dirigent/v1
+kind: pipeline
+code: wikidata-country-reference
+name: Country code reference from Wikidata
+description: |
+  ISO 3166-1 alpha-2, alpha-3 and numeric codes for every sovereign state, read from
+  **Wikidata** over SPARQL and saved as a json reference table other pipelines read.
+
+tags: [open-data, http, storage, transform, sparql]
+
+requires:
+  blocks:
+    - http.request
+    - transform.jq
+    - storage.write
+    - storage.read
+
+params:
+  type: object
+  additionalProperties: false
+  properties:
+    language:
+      type: string
+      default: en
+      description: The label language, as the Wikidata label service names it.
+    user_agent:
+      type: string
+      default: dirigent-example/1.0 (https://github.com/winterop-com/dirigent)
+      description: Required by the endpoint's terms of use; say who you are and how to be reached.
+
+steps:
+  fetch:
+    block: http.request
+    # The endpoint queues queries behind a shared budget and answers 429 when it is busy, so
+    # the wait between tries is longer than the query itself takes.
+    retry:
+      max_attempts: 3
+      backoff: 20s
+    config:
+      url: https://query.wikidata.org/sparql
+      headers:
+        # Without this the answer is XML, which is the endpoint's default.
+        Accept: application/sparql-results+json
+        User-Agent: ${params.user_agent}
+      query:
+        query: |
+          SELECT ?item ?itemLabel ?iso2 ?iso3 ?isoNumeric WHERE {
+            ?item wdt:P31 wd:Q3624078 .
+            ?item wdt:P298 ?iso3 .
+            OPTIONAL { ?item wdt:P297 ?iso2 }
+            OPTIONAL { ?item wdt:P299 ?isoNumeric }
+            SERVICE wikibase:label { bd:serviceParam wikibase:language "${params.language}". }
+          }
+          ORDER BY ?iso3
+      # A cold query against a busy endpoint can take most of a minute.
+      timeout: 90s
+
+  table:
+    block: transform.jq
+    depends_on: [fetch]
+    config:
+      input: ${steps.fetch.output.body}
+      # Every binding is {type, value} and every value is a string, so the numeric code is
+      # converted here rather than being carried as "454" for the rest of its life. An
+      # OPTIONAL that matched nothing has no binding at all, which is why each read is
+      # guarded rather than defaulted after the fact.
+      program: |
+        [.results.bindings[]
+         | {
+             wikidata_id: (.item.value | sub("^.*/"; "")),
+             name: .itemLabel.value,
+             iso2: (if .iso2 then .iso2.value else null end),
+             iso3: .iso3.value,
+             iso_numeric: (if .isoNumeric then (.isoNumeric.value | tonumber) else null end)
+           }]
+        | unique_by(.iso3)
+
+  publish:
+    block: storage.write
+    depends_on: [table]
+    config:
+      target: ${run.scratch}/countries.json
+      value: ${steps.table.output.value}
+
+  recalled:
+    block: storage.read
+    depends_on: [publish]
+    config:
+      # The read another pipeline would do: the table by its path, and the count below is off
+      # the object rather than off the value upstream.
+      source: ${steps.publish.output.uri}
+      max_size: 4mb
+
+  summary:
+    block: transform.jq
+    depends_on: [recalled]
+    config:
+      input: ${steps.recalled.output.value}
+      program: |
+        {
+          countries: length,
+          with_iso2: ([.[] | select(.iso2 != null)] | length),
+          with_numeric: ([.[] | select(.iso_numeric != null)] | length),
+          sample: (sort_by(.iso3) | .[0:3])
+        }

dirigent_examples/shelves/open-data/world-bank-population-trend.yaml

@@ -0,0 +1,166 @@
+# Sixty years of population for one country, with year-on-year growth worked out on the way past.
+#
+# The World Bank's indicator API is keyless and answers a two-element array: the first element
+# is the paging envelope, {page, pages, per_page, total, lastupdated}, and the second is the list
+# of observations, newest year first. Nothing is nested inside anything else, so `.[0]` and
+# `.[1]` are the whole access pattern -- and reading a page count out of `.[0]` is what makes
+# paging visible rather than assumed.
+#
+# On paging: dirigent's format has no loop, so "keep fetching until the pages run out" is not a
+# step. The honest single-hop version is the one below: ask for a page large enough to hold the
+# whole series, then check the envelope and refuse the run if the answer says there was more.
+# A truncated series that looks complete is the failure worth spending a step on.
+#
+# What happens, hop by hop:
+#
+#   fetch     one GET. per_page is a parameter because it is the thing you raise when the
+#             series is longer than the default guess.
+#   whole     the paging check. jq's error() fails the step, so a series that did not fit
+#             stops here instead of reaching the gate looking well-formed.
+#   trend     the arithmetic. The API answers newest-first, so the series is reversed into
+#             chronological order and each row is paired with the one before it. A missing
+#             year, or the first year, has no growth to report, and gets null rather than
+#             zero: zero would mean the population did not change.
+#   gate      validate.schema against the shape written below. The gate passes the value
+#             through, so the step below reads the gate rather than the trend, and the document
+#             itself records that nothing reached the csv without being checked.
+#   checked   storage.write, the checked rows as json. A converter reads one URI and writes
+#             another, so the only object the csv can be made from is the one the gate passed.
+#   report    json to csv, from that object.
+#
+# To make it yours: change country to any ISO3 code and indicator to any World Bank series code
+# -- SP.DYN.LE00.IN for life expectancy, NY.GDP.PCAP.CD for GDP per head -- and widen the
+# schema's population bounds if the indicator you pick is not a count of people.
+#
+#   dg run --local examples/open-data/world-bank-population-trend.yaml
+#   dg run --local examples/open-data/world-bank-population-trend.yaml -p country=NPL -p per_page=40
+
+format: dirigent/v1
+kind: pipeline
+code: world-bank-population-trend
+name: World Bank population trend
+description: |
+  One country's population series from the **World Bank indicator API**, with year-on-year
+  growth computed in jq, checked against a carried schema and written as csv.
+
+  A server refuses a document that carries a schema, so this one is for a `--local` or
+  standalone run; on an instance, the same shape is created once with `dg schema create`.
+
+tags: [open-data, http, storage, transform, validate, csv]
+
+requires:
+  blocks:
+    - http.request
+    - transform.jq
+    - validate.schema
+    - storage.write
+    - convert.std
+
+# Carried in the document so the gate needs nothing handed to it. The bounds are not
+# decoration: a year outside them, or a negative population, means the API moved under us.
+schemas:
+  population-trend-row:
+    type: array
+    minItems: 1
+    items:
+      type: object
+      required: [country, iso3, year, population, growth_pct]
+      additionalProperties: false
+      properties:
+        country: { type: string }
+        iso3: { type: string, minLength: 3, maxLength: 3 }
+        year: { type: integer, minimum: 1960, maximum: 2100 }
+        population: { type: [integer, "null"], minimum: 0 }
+        growth_pct: { type: [number, "null"] }
+
+params:
+  type: object
+  additionalProperties: false
+  properties:
+    country:
+      type: string
+      default: MWI
+      description: ISO3 country code, as it appears in the request path.
+    indicator:
+      type: string
+      default: SP.POP.TOTL
+      description: A World Bank series code; the default is total population.
+    per_page:
+      type: integer
+      default: 100
+      minimum: 1
+      description: Raise this when the paging check refuses a series longer than one page.
+
+steps:
+  fetch:
+    block: http.request
+    config:
+      url: https://api.worldbank.org/v2/country/${params.country}/indicator/${params.indicator}
+      query:
+        # Without format=json the API answers XML, which is its own default and nobody's
+        # convenience.
+        format: json
+        per_page: ${params.per_page}
+        page: 1
+
+  whole:
+    block: transform.jq
+    depends_on: [fetch]
+    config:
+      input: ${steps.fetch.output.body}
+      # The envelope, checked and then dropped: everything below works on the observations.
+      program: |
+        .[0] as $meta
+        | if $meta.pages > 1
+          then error("the series has \($meta.pages) pages of \($meta.per_page); raise per_page to at least \($meta.total)")
+          else .[1]
+          end
+
+  trend:
+    block: transform.jq
+    depends_on: [whole]
+    config:
+      input: ${steps.whole.output.value}
+      # Chronological order first, because "the year before" is meaningless in the order the
+      # API answers in. The window is a pair, so index 0 has no predecessor and no growth.
+      program: |
+        [.[] | {country: .country.value,
+                iso3: .countryiso3code,
+                year: (.date | tonumber),
+                population: .value}]
+        | sort_by(.year)
+        | . as $series
+        | [range($series | length) as $i
+           | $series[$i]
+           | . + {growth_pct:
+                    (if $i == 0 then null
+                     else ($series[$i - 1].population) as $before
+                       | if $before == null or .population == null or $before == 0 then null
+                         else ((.population - $before) / $before * 1000 | round / 10)
+                         end
+                     end)}]
+
+  gate:
+    block: validate.schema
+    depends_on: [trend]
+    config:
+      input: ${steps.trend.output.value}
+      schema: population-trend-row
+
+  checked:
+    block: storage.write
+    depends_on: [gate]
+    config:
+      # Reading the gate rather than the trend is what proves, in the document, that only a
+      # checked value reaches the csv.
+      target: ${run.scratch}/${params.country}-${params.indicator}.json
+      value: ${steps.gate.output.value}
+
+  report:
+    block: convert.std
+    depends_on: [checked]
+    config:
+      source: ${steps.checked.output.uri}
+      target: ${run.scratch}/${params.country}-${params.indicator}.csv
+      from: json
+      to: csv

dirigent_examples/shelves/patterns/README.md

@@ -0,0 +1,144 @@
+# Engine patterns
+
+One engine behaviour per file, named for what it shows. Where the other shelves are organised
+by what a pipeline is *for* -- moving data, reshaping it, waiting for it -- this one is
+organised by what the engine *does*: the edge conditions, the retry policy, the two clocks, the
+item policies, the trigger declarations, the concurrency policies, and the reference language.
+
+Every document here runs for real. The HTTP ones call [Postman Echo](https://postman-echo.com),
+a public request-and-response service, so nothing has to be stood up first; the rest are
+offline. None of them needs `--enable-unsafe`: no file on this shelf runs code on the worker.
+
+Each header says what the pipeline demonstrates end to end, what each hop hands on, what to
+change, and **what outcome to expect** -- because several of these fail on purpose, and a file
+whose lesson is a failure has to say so before you run it.
+
+## Trigger rules
+
+The edge condition on `depends_on`. Each of these fails a step deliberately, with
+`/status/500`, so the rule has something to react to.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [rule-all-success.yaml](rule-all-success.yaml) | The default: a failure skips everything below it | `failed` |
+| [rule-all-done.yaml](rule-all-done.yaml) | Cleanup that runs whichever way the branch went | `failed` |
+| [rule-one-failed.yaml](rule-one-failed.yaml) | The handler branch, and the success branch it excludes | `failed` |
+| [rule-always.yaml](rule-always.yaml) | The widest edge, and the ordering it still respects | `failed` |
+
+## Retries
+
+Whether a failed attempt earns another one, and how long it waits first.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [retry-exponential-backoff.yaml](retry-exponential-backoff.yaml) | The five fields, and the 1s, 2s, 4s they compute | `failed` |
+| [retry-with-jitter.yaml](retry-with-jitter.yaml) | Why four items that failed together must not retry together | `completed_with_errors` |
+| [retry-budget-exhausted.yaml](retry-budget-exhausted.yaml) | A budget spent in full on a hopeless failure | `failed` |
+| [retry-only-transient.yaml](retry-only-transient.yaml) | The same policy on a 500 and a 404: three attempts and one | `completed_with_errors` |
+
+## Timeouts and deadlines
+
+Three clocks that stop a step, and they are not interchangeable.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [timeout-fails-the-step.yaml](timeout-fails-the-step.yaml) | `timeout` bounds one block call, and expires as transient | `failed` |
+| [timeout-skips-the-step.yaml](timeout-skips-the-step.yaml) | `on_timeout: skip` turns an expired deadline into a quiet day | `succeeded` |
+| [deadline-on-a-sensor.yaml](deadline-on-a-sensor.yaml) | `poll`, `deadline` and the default `on_timeout: fail` | `failed` |
+| [poll-cadence.yaml](poll-cadence.yaml) | The same wait polled two ways, with the overshoot measured | `succeeded` |
+
+## Fan-out
+
+One step definition, many run items.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [fan-out-literal-list.yaml](fan-out-literal-list.yaml) | `for_each` written out in the document | `succeeded` |
+| [fan-out-from-params.yaml](fan-out-from-params.yaml) | Width supplied by the caller, and the schema that guards it | `succeeded` |
+| [fan-out-fail-fast.yaml](fan-out-fail-fast.yaml) | The default item policy: one bad element sinks the batch | `failed` |
+| [fan-out-continue.yaml](fan-out-continue.yaml) | `items: continue`, and the failed item that is *absent* downstream | `completed_with_errors` |
+| [fan-out-then-join.yaml](fan-out-then-join.yaml) | The join, which is just a step with no `for_each` of its own | `succeeded` |
+| [fan-out-nested-objects.yaml](fan-out-nested-objects.yaml) | Elements that are objects, and `${item.limits.max_ms}` | `succeeded` |
+| [fan-out-item-wise.yaml](fan-out-item-wise.yaml) | A second fan-out over the same grid, and the item it pairs with | `succeeded` |
+
+## Parameters
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [params-every-type.yaml](params-every-type.yaml) | Every type and keyword, and why `format` needs a gate to assert | `succeeded` |
+| [params-validation-refuses.yaml](params-validation-refuses.yaml) | What a bad run request is answered with, before a run exists | `succeeded` |
+
+## Triggers
+
+What starts a run on its own. The declarations travel with the document; the operational state
+stays on the instance.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [schedule-cron-timezone.yaml](schedule-cron-timezone.yaml) | Five columns, and the named zone that decides what they mean | `succeeded` |
+| [schedule-interval.yaml](schedule-interval.yaml) | A cadence rather than a calendar, and the misfire grace | `succeeded` |
+| [schedule-at-once.yaml](schedule-at-once.yaml) | One instant, anchored in the zone the schedule declares | `succeeded` |
+| [schedule-window-half-open.yaml](schedule-window-half-open.yaml) | `${run.window.*}`, half-open; needs `--window` | `succeeded` |
+| [webhook-mapping-nested-payload.yaml](webhook-mapping-nested-payload.yaml) | JSONPaths onto parameters, and the parameter left unreachable | `succeeded` |
+| [webhook-signed.yaml](webhook-signed.yaml) | Outbound HMAC with `sign_with`, and where each secret lives | `succeeded` |
+
+## Concurrency
+
+What a second trigger does while a run is still going. Each header spells that out; a single
+local run has nothing to collide with, so the policies are exercised against a server.
+
+| File | What a second trigger does | Ends as |
+| --- | --- | --- |
+| [concurrency-skip.yaml](concurrency-skip.yaml) | No run is created at all | `succeeded` |
+| [concurrency-queue.yaml](concurrency-queue.yaml) | The run is created and held, with its parameters frozen | `succeeded` |
+| [concurrency-replace.yaml](concurrency-replace.yaml) | The run in flight is cancelled, remotes told | `succeeded` |
+
+## Composition
+
+`pipeline.run`, and the four questions a call answers. All of them need the child, which a
+local run is handed with `--also-apply examples/patterns/pipeline-run-child.yaml`.
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [pipeline-run-child.yaml](pipeline-run-child.yaml) | The called pipeline, which knows nothing about parents | `succeeded` |
+| [pipeline-run-wait.yaml](pipeline-run-wait.yaml) | `wait: true`: a parked row, not a held worker | `succeeded` |
+| [pipeline-run-fire-and-forget.yaml](pipeline-run-fire-and-forget.yaml) | `wait: false`: a fork, and the run id that is the whole handoff | `succeeded` |
+| [pipeline-run-strict.yaml](pipeline-run-strict.yaml) | `strict`, and the third status it is about | `failed` |
+| [pipeline-run-with-params.yaml](pipeline-run-with-params.yaml) | A fan-out of children, checked against the child's schema | `succeeded` |
+
+## The rest of the engine
+
+| File | What it shows | Ends as |
+| --- | --- | --- |
+| [step-names-and-keys.yaml](step-names-and-keys.yaml) | The map key addresses; `name` describes and identifies nothing | `succeeded` |
+| [outputs-inline-vs-storage.yaml](outputs-inline-vs-storage.yaml) | The 16KB inline threshold the engine decides on its own, against `storage.write` and `storage.read` as the document's own choice | `succeeded` |
+| [references-cheat-sheet.yaml](references-cheat-sheet.yaml) | Every `${...}` form, each used once; needs `--window` | `succeeded` |
+| [sensor-http-ready.yaml](sensor-http-ready.yaml) | A 503 as "not yet" rather than as an error | `succeeded` |
+| [sensor-storage-exists.yaml](sensor-storage-exists.yaml) | A glob, a size floor, and a drop that actually lands | `succeeded` |
+| [log-levels.yaml](log-levels.yaml) | `--log-level PATTERN=LEVEL`, a run setting rather than a document one | `succeeded` |
+| [priority-layered.yaml](priority-layered.yaml) | `priority` on the document, on a schedule, and on one ad hoc run | `succeeded` |
+| [connections-referenced-vs-carried.yaml](connections-referenced-vs-carried.yaml) | Named, carried, and absolute; needs `--connections` | `succeeded` |
+
+## Running them
+
+Most take no flags at all:
+
+```bash
+dg run --local examples/patterns/rule-one-failed.yaml
+```
+
+Four need something handed to them, because what they demonstrate is exactly the thing a bare
+local run does not have:
+
+```bash
+dg run --local examples/patterns/references-cheat-sheet.yaml --window 2026-06-01..2026-06-02
+dg run --local examples/patterns/schedule-window-half-open.yaml --window 2026-06-01..2026-06-02
+dg run --local examples/patterns/connections-referenced-vs-carried.yaml \
+  --connections examples/connections.yaml
+dg run --local examples/patterns/pipeline-run-wait.yaml \
+  --also-apply examples/patterns/pipeline-run-child.yaml
+```
+
+Run the two without their flag once, on purpose: a run with no window refuses
+`${run.window.start}` by name rather than resolving it to an empty string, which is the whole
+argument for the reference language raising instead of defaulting.

dirigent_examples/shelves/patterns/concurrency-queue.yaml

@@ -0,0 +1,89 @@
+# concurrency: queue -- a second trigger becomes a run that is created and held.
+#
+# WHAT A SECOND TRIGGER DOES HERE: the run IS created. It exists from the moment it is
+# triggered, with its parameters and its window frozen as they were at that instant, and it
+# simply does not advance -- no step is claimable while the slot is occupied. When the run
+# ahead of it settles, the oldest held run is released and starts.
+#
+# That is the difference from skip, and it is the difference between losing work and delaying
+# it. Use queue whenever a firing has work of its own that nothing later will redo: consuming
+# a queue, appending a day's rows, advancing a cursor, sending a batch. The cost is that a
+# backlog is real -- if the pipeline is consistently slower than its cadence, held runs
+# accumulate, and that is a fact to look at rather than something the policy hides.
+#
+# THE PARAMETERS ARE FROZEN AT TRIGGER TIME, NOT AT RELEASE TIME. A run held for an hour still
+# carries the parameters and the window it was created with, so an hourly increment released
+# late covers the hour it was for, not the hour it happened to start in. That is the whole
+# reason the run is created up front rather than the trigger being remembered.
+#
+# Everything about the ordering is FIFO: the oldest held run is the one released. A run
+# cancelled while held simply never occupied the slot, and releasing does not double up.
+#
+# Hop by hop:
+#
+#   claim_batch  a sleep standing in for the work a firing owns -- the batch nothing else will
+#                pick up if this run never happens.
+#   commit       records what the batch amounted to.
+#
+# EXPECT THIS RUN TO SUCCEED in about five seconds. A single local run has nothing to queue
+# behind, so the policy is exercised against a server:
+#
+#   dg run --local examples/patterns/concurrency-queue.yaml
+#   dg apply examples/patterns/concurrency-queue.yaml
+#   dg run concurrency-queue -p batch=1 &
+#   dg run concurrency-queue -p batch=2      # created, and held
+#   dg runs list concurrency-queue           # two runs; the second starts when the first settles
+
+format: dirigent/v1
+kind: pipeline
+code: concurrency-queue
+name: A second run that waits its turn
+description: |
+  `concurrency: queue` creates the second run and holds it: no step advances until the slot
+  is free, and then the oldest held run is released.
+
+  Its parameters and window are frozen at trigger time, so an increment released late still
+  covers the interval it was created for.
+
+tags: [patterns, sensor, transform, concurrency]
+
+# The one line this file is about.
+concurrency: queue
+
+requires:
+  blocks:
+    - time.sleep
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    batch:
+      type: integer
+      description: Which batch this firing owns; nothing else will pick it up.
+      default: 1
+      minimum: 1
+    seconds:
+      type: integer
+      description: How long the batch takes; long enough to queue a second run by hand.
+      default: 4
+      minimum: 1
+      maximum: 120
+
+steps:
+  claim_batch:
+    block: time.sleep
+    poll: 1s
+    config:
+      for: "${params.seconds}s"
+
+  commit:
+    block: transform.jq
+    depends_on: [claim_batch]
+    # An append rather than a rebuild, which is what makes queue the right policy: a firing
+    # that never ran is a batch nobody ever committed.
+    config:
+      input:
+        batch: "${params.batch}"
+      program: |
+        {committed: .batch, incremental: true}

dirigent_examples/shelves/patterns/concurrency-replace.yaml

@@ -0,0 +1,92 @@
+# concurrency: replace -- the newest trigger wins, and the run in flight is cancelled.
+#
+# WHAT A SECOND TRIGGER DOES HERE: every run currently in flight is CANCELLED, with the reason
+# "replaced by a newer run", and the new run starts. Cancellation is not a suggestion -- what
+# has not started is stopped, and an attempt holding a remote handle has its remote told, so a
+# job submitted to something else is not left running behind a cancelled run.
+#
+# This is the "only the latest matters" policy, and it is the one to be most careful with,
+# because it is the only one that destroys work already done. It fits a preview build, a
+# dashboard refresh triggered by every commit, a re-render of a view where an older answer has
+# no value the moment a newer request exists. It does not fit anything that writes: a load
+# cancelled halfway is a load somebody has to reason about.
+#
+# THE ORDER OF OPERATIONS MATTERS AND IS WORTH KNOWING. A fan-out is expanded BEFORE the
+# policy decides anything, so a document whose expansion would be refused is refused before
+# any cancelling happens -- a refusal after the cancel would leave the old run dead and the
+# new one non-existent.
+#
+# A cancelled run frees the slot exactly as a finished one does, and it settles as cancelled,
+# which is neither succeeded nor failed. It stays in the run list with its attempts and logs:
+# replaced is a thing to be able to see, not a thing to erase.
+#
+# Hop by hop:
+#
+#   render   a sleep standing in for a build whose older answer stops mattering the instant a
+#            newer request arrives.
+#   publish  swaps the freshly rendered output in. It only ever runs for the newest request,
+#            which is the property this policy buys.
+#
+# EXPECT THIS RUN TO SUCCEED in about five seconds. A single local run has nothing to replace,
+# so the policy is exercised against a server -- watch the first run settle as cancelled:
+#
+#   dg run --local examples/patterns/concurrency-replace.yaml
+#   dg apply examples/patterns/concurrency-replace.yaml
+#   dg run concurrency-replace -p revision=abc123 &
+#   dg run concurrency-replace -p revision=def456   # the first is cancelled, this one starts
+#   dg runs list concurrency-replace                # one cancelled, one succeeded
+
+format: dirigent/v1
+kind: pipeline
+code: concurrency-replace
+name: The newest trigger wins
+description: |
+  `concurrency: replace` cancels every run in flight, telling any remote about the attempts
+  that had one, and starts the new run.
+
+  The only policy that destroys work already done. Right for a preview render whose older
+  answer is worthless; wrong for anything that writes.
+
+tags: [patterns, sensor, transform, concurrency]
+
+# The one line this file is about.
+concurrency: replace
+
+requires:
+  blocks:
+    - time.sleep
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    revision:
+      type: string
+      description: Which revision is being rendered; only the newest one matters.
+      default: abc123
+      minLength: 1
+      maxLength: 64
+    seconds:
+      type: integer
+      description: How long the render takes; long enough to replace it by hand.
+      default: 4
+      minimum: 1
+      maximum: 120
+
+steps:
+  render:
+    block: time.sleep
+    poll: 1s
+    config:
+      for: "${params.seconds}s"
+
+  publish:
+    block: transform.jq
+    depends_on: [render]
+    # Nothing above this step writes anywhere, which is what makes cancelling it safe. A
+    # pipeline whose first step wrote to a real system would want queue and not this.
+    config:
+      input:
+        revision: "${params.revision}"
+      program: |
+        {published: .revision, superseded_anything_older: true}