dirigent-examples 0.15.0__py3-none-any.whl

dirigent_examples/shelves/transform/xml-feed-to-ndjson.yaml

@@ -0,0 +1,116 @@
+# An XML feed read as records, one line each, and the mapping that makes it reversible.
+#
+# convert.std reads an element as an object: an attribute is a key prefixed with @, the text
+# of an element with no children is the bare string, a child element is a key of its tag, and
+# a tag that repeats is a list in document order. Nothing else fits in, so mixed content --
+# text sitting beside child elements -- is refused naming the element rather than flattened.
+#
+# xml to ndjson is the direction that scales: the root's children are the records, read with
+# iterparse and dropped as they are written, so a feed far larger than memory converts. It is
+# one-way, because an ndjson line carries no root element name to write a document under;
+# xml to json is the pair that round-trips, and this document runs both over the one feed
+# object it stores first.
+#
+# A conversion names two uris and carries no value, so each direction here lands in the run's
+# scratch space and a storage.read is what brings it back in: the ndjson as text a jq program
+# splits, the json as the value it already is.
+#
+# Everything read out of an element is text, exactly as it is out of a csv: 4.5 is the three
+# characters until a jq program says tonumber.
+#
+#   dg run --local examples/transform/xml-feed-to-ndjson.yaml --keep
+
+format: dirigent/v1
+kind: pipeline
+code: xml-feed-to-ndjson
+name: An XML feed as records
+description: |
+  Store an XML feed, convert it to one record per line, aggregate the records with jq, and
+  convert the same object to one whole value to show the mapping that round-trips.
+
+  The mapping, in four rules:
+
+  1. an attribute is a key prefixed with `@`
+  2. an element's text is the value where it has no children
+  3. a child element is a key of its tag
+  4. a tag that repeats is a list, in document order
+
+tags: [transform, storage]
+
+requires:
+  blocks:
+    - convert.std
+    - transform.jq
+    - storage.read
+    - storage.write
+
+steps:
+  feed:
+    block: storage.write
+    config:
+      target: ${run.scratch}/feed.xml
+      # Written inline so the example needs no network. In a real pipeline this object is
+      # the feed an upstream http.request put in storage, and records starts there.
+      text: |
+        <?xml version="1.0" encoding="utf-8"?>
+        <feed source="stations">
+          <reading station="st-1"><region>east</region><celsius>4.5</celsius></reading>
+          <reading station="st-2"><region>east</region><celsius>-3.0</celsius></reading>
+          <reading station="st-3"><region>west</region><celsius>1.2</celsius></reading>
+        </feed>
+      content_type: application/xml
+
+  records:
+    block: convert.std
+    depends_on: [feed]
+    config:
+      source: ${steps.feed.output.uri}
+      target: ${run.scratch}/readings.ndjson
+      from: xml
+      # The records are the root's children, so each <reading> becomes one line. The root's
+      # own attribute, source="stations", is not on any of them: it belongs to the document,
+      # and the json direction below is where it survives.
+      to: ndjson
+
+  lines:
+    block: storage.read
+    depends_on: [records]
+    config:
+      source: ${steps.records.output.target}
+      # Nothing records what an .ndjson object is, and an object a read cannot name is
+      # refused rather than guessed at, so the step says it here.
+      content_type: application/x-ndjson
+
+  mean_by_region:
+    block: transform.jq
+    depends_on: [lines]
+    config:
+      # ndjson is one JSON value per line and is text rather than the JSON family, so the
+      # read handed over text and the program splits before it parses. tonumber for the one
+      # field it wants as a number.
+      input: ${steps.lines.output.text}
+      program: |
+        split("\n")
+        | map(select(length > 0) | fromjson)
+        | group_by(.region)
+        | [.[] | {region: .[0].region,
+                  stations: [.[] | ."@station"],
+                  mean_celsius: ([.[] | .celsius | tonumber] | add / length)}]
+
+  whole_document:
+    block: convert.std
+    depends_on: [feed]
+    config:
+      # The same feed the other way: one object, keyed by the root element's tag, carrying
+      # the document's own @source and the repeated readings as a list. This is the pair
+      # that round-trips -- json to xml writes this object back out as the feed.
+      source: ${steps.feed.output.uri}
+      target: ${run.scratch}/feed.json
+      from: xml
+      to: json
+
+  document:
+    block: storage.read
+    depends_on: [whole_document]
+    config:
+      source: ${steps.whole_document.output.target}

dirigent_examples/shelves/transform/yaml-config-to-json.yaml

@@ -0,0 +1,104 @@
+# A YAML document is one value, so a config file converts to the object it describes.
+#
+# This is the half of convert.std that is not the sequence of records: yaml and json trade
+# one whole value in either direction, so a settings file becomes a JSON object a jq program
+# can read, and a JSON value becomes a YAML document again. The stream spelling -- one `---`
+# document per ndjson line -- is the other half, and examples/transform/ndjson-round-trip.yaml
+# is where the sequence side lives.
+#
+# The config is an object in storage from the first hop, because a conversion reads a uri
+# and writes a uri and never holds a value. storage.read is what brings the parsed config
+# into the run for jq, and storage.write is what puts the answer back where the last
+# conversion can pick it up.
+#
+# The one thing to know before pointing this at a real file: YAML says things JSON cannot.
+# An unquoted 2026-03-01 is a date, not a string, and the codec refuses it naming its path
+# rather than guessing what text it meant. That is why the retention date below is quoted.
+#
+#   dg run --local examples/transform/yaml-config-to-json.yaml --keep
+
+format: dirigent/v1
+kind: pipeline
+code: yaml-config-to-json
+name: A config as an object
+description: |
+  Read a stored YAML config as the JSON object it describes, take what a run needs out of
+  it, and write the answer back out as YAML.
+
+  `convert.std` reads `yaml` two ways. This document uses the first:
+
+  1. one **document** is one value, traded with `json`
+  2. one **stream** of documents is one line each, traded with `ndjson`
+
+tags: [transform, storage]
+
+requires:
+  blocks:
+    - convert.std
+    - transform.jq
+    - storage.read
+    - storage.write
+
+steps:
+  config:
+    block: storage.write
+    config:
+      target: ${run.scratch}/settings.yaml
+      # Written inline so the example needs no network. In a real pipeline this object is
+      # the config a git.checkout or an http.request put in storage, and parse starts there.
+      text: |
+        name: daily-load
+        schedule: 0 3 * * *
+        # Quoted, because an unquoted date is a YAML date and JSON has no date: the codec
+        # refuses it at $.retention.before rather than deciding what text it meant.
+        retention:
+          before: "2026-03-01"
+        targets:
+          - code: warehouse
+            enabled: true
+          - code: archive
+            enabled: false
+      content_type: application/yaml
+
+  parse:
+    block: convert.std
+    depends_on: [config]
+    config:
+      source: ${steps.config.output.uri}
+      target: ${run.scratch}/settings.json
+      from: yaml
+      to: json
+
+  settings:
+    block: storage.read
+    depends_on: [parse]
+    config:
+      source: ${steps.parse.output.target}
+
+  enabled:
+    block: transform.jq
+    depends_on: [settings]
+    config:
+      # What the read handed over is the config as a value: keys are keys, and true is a
+      # boolean rather than the word.
+      input: ${steps.settings.output.value}
+      program: |
+        {name, schedule, before: .retention.before,
+         targets: [.targets[] | select(.enabled) | .code]}
+
+  store:
+    block: storage.write
+    depends_on: [enabled]
+    config:
+      target: ${run.scratch}/enabled.json
+      value: ${steps.enabled.output.value}
+
+  as_yaml:
+    block: convert.std
+    depends_on: [store]
+    config:
+      # Back the way it came: one JSON value, one YAML document.
+      source: ${steps.store.output.uri}
+      target: ${run.scratch}/enabled.yaml
+      from: json
+      to: yaml

dirigent_examples/shelves/triggers/README.md

@@ -0,0 +1,45 @@
+# Trigger examples
+
+What starts a run on its own: a clock, or an inbound webhook. A trigger is declared in the
+document and materialised by `dg apply`; the scheduler fires the clocks and the server
+answers the hooks, on the instance the document was applied to. Operational state -- paused,
+last fired, the firing and delivery history -- stays in the instance, so none of it appears
+in these files. [docs/design.md](../../docs/design.md#the-misfire-policy) is the page behind
+the clocks.
+
+Each file is prefixed with the clock kind it teaches, the way `transform/`'s files are
+prefixed with the engine kind: `cron-` for a calendar moment, `interval-` for a rolling
+cadence, `at-` for a single firing. Every one of them also runs ad hoc, with nothing on the
+allowlist and no network:
+
+```bash
+dg run --local examples/triggers/cron-nightly.yaml -p day=2026-01-01
+```
+
+One of them reads the window its firing covers, which no document declares and only a run
+carries, so running it ad hoc means saying which interval it is for:
+
+```bash
+dg run --local examples/triggers/cron-windowed.yaml --window 2026-06-01..2026-06-02
+```
+
+## Pipelines
+
+| File | What it teaches |
+| --- | --- |
+| [cron-nightly.yaml](cron-nightly.yaml) | A calendar moment: five in the morning in the schedule's own zone, across daylight saving, with parameters pinned over the pipeline's defaults. |
+| [cron-windowed.yaml](cron-windowed.yaml) | The interval a firing covers rather than the moment it happened at: `${run.window.start}` and `${run.window.end}`, derived from the cadence and read like a parameter. |
+| [interval-rolling.yaml](interval-rolling.yaml) | A rolling cadence: when an interval beats a cron, and the misfire grace that turns a weekend outage into one firing rather than sixty. |
+| [at-one-time.yaml](at-one-time.yaml) | The one-time firing: the backfill and the launch, and how a moment written without an offset is read in the schedule's own zone. |
+| [managed-and-manual.yaml](managed-and-manual.yaml) | Against a real instance: what an apply materialises, what it removes, and the hand-made schedule it leaves alone. |
+| [document-nightly.yaml](document-nightly.yaml) | A `kind: triggers` document: clocks for a pipeline defined elsewhere, owning its own rows and refusing a pipeline no instance holds. |
+| [webhook-trigger.yaml](webhook-trigger.yaml) | The inbound trigger: a token minted at apply, a strict payload-to-parameter mapping, and everything else in the POST ignored. |
+
+A pipeline carries as many schedules as it needs, each with its own zone and its own
+parameters: nightly against production and hourly against staging is two schedules on one
+pipeline, never two pipelines.
+
+Every file here but one is a pipeline document that carries its own clocks, which is the
+primary form: one file is one deployable unit, and its digest versions the triggers with the
+steps. `document-nightly.yaml` is the other form, for a pipeline somebody else's file
+defines -- it names `managed-and-manual`, so read the two together.

dirigent_examples/shelves/triggers/at-one-time.yaml

@@ -0,0 +1,78 @@
+# The third clock: one firing, at one instant, and then never again.
+#
+# The schedule fires only on an instance this document has been applied to. The same
+# document runs ad hoc anywhere, with nothing on the allowlist and no network:
+#
+#   dg run --local examples/triggers/at-one-time.yaml -p from=2025-01-01 -p to=2025-12-31
+#   dg apply examples/triggers/at-one-time.yaml        # against an instance
+#   dg schedule list at-one-time
+#
+# This is the backfill and the launch: a job that has to happen once, at a moment agreed
+# with somebody, and that nobody should have to be awake for. Declaring it in the document
+# makes the moment reviewable in a pull request rather than typed into a terminal at night.
+
+format: dirigent/v1
+kind: pipeline
+code: at-one-time
+name: A single agreed instant
+description: A one-time schedule firing a bounded backfill at a single agreed instant.
+
+tags: [triggers, transform, schedule]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    from:
+      type: string
+      format: date
+      description: First day of the backfill window, inclusive.
+      default: "2026-01-01"
+    to:
+      type: string
+      format: date
+      description: Last day of the backfill window, inclusive.
+      default: "2026-01-07"
+    environment:
+      type: string
+      enum: [staging, production]
+      default: staging
+
+steps:
+  window:
+    block: transform.jq
+    config:
+      input:
+        from: "${params.from}"
+        to: "${params.to}"
+        environment: "${params.environment}"
+      program: |
+        {environment, from, to, months: [range(1; 13)]}
+
+  backfill:
+    block: transform.jq
+    depends_on: [window]
+    config:
+      input: "${steps.window.output.value}"
+      program: |
+        {environment, backfilled: "\(.from)..\(.to)", batches: (.months | length)}
+
+triggers:
+  schedules:
+    - code: launch-backfill
+      # A moment written without an offset is anchored in the zone this schedule declares,
+      # not in UTC and not in the host's local time: this is half past four in the morning
+      # in Oslo. Write the offset yourself -- 2027-01-06T03:30:00+00:00 -- and it is taken
+      # as given and the zone below is not consulted.
+      at: 2027-01-06 04:30:00
+      timezone: Europe/Oslo
+      # Once the instant has gone by there is no next firing, so the schedule pauses itself
+      # rather than being deleted: its parameters and its firing history stay readable with
+      # dg schedule firings at-one-time launch-backfill.
+      params:
+        from: "2025-01-01"
+        to: "2025-12-31"
+        environment: production

dirigent_examples/shelves/triggers/cron-nightly.yaml

@@ -0,0 +1,79 @@
+# A calendar moment: five in the morning, Oslo time, every day.
+#
+# The schedule fires only on an instance this document has been applied to. The same
+# document runs ad hoc anywhere, with nothing on the allowlist and no network:
+#
+#   dg run --local examples/triggers/cron-nightly.yaml -p day=2026-01-01
+#   dg apply examples/triggers/cron-nightly.yaml       # against an instance
+#   dg schedule list cron-nightly
+#
+# The pipeline is deliberately trivial -- one jq program shaping a small report -- because
+# what this file teaches is the clock above it, not the work below it.
+
+format: dirigent/v1
+kind: pipeline
+code: cron-nightly
+name: Nightly load
+description: |
+  One pipeline on a nightly cron schedule, in its own timezone, with pinned parameters.
+
+  What this file teaches is the **clock**, not the work below it. The zone belongs
+  to the schedule rather than to whichever host runs the scheduler, so `0 5 * * *`
+  in `Europe/Oslo` stays five in the morning across a daylight-saving boundary.
+
+tags: [triggers, transform, schedule]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    day:
+      type: string
+      format: date
+      description: The day being loaded, which the schedule pins for every firing.
+      default: "2026-01-01"
+    environment:
+      type: string
+      enum: [staging, production]
+      default: staging
+
+steps:
+  plan:
+    block: transform.jq
+    config:
+      input:
+        day: "${params.day}"
+        environment: "${params.environment}"
+      program: |
+        {day, environment, datasets: ["cases", "climate"]}
+
+  report:
+    block: transform.jq
+    depends_on: [plan]
+    config:
+      input: "${steps.plan.output.value}"
+      program: |
+        {loaded: .day, environment: .environment, datasets: (.datasets | length)}
+
+triggers:
+  schedules:
+    - code: nightly
+      # A trigger carries the same pair: a code that addresses it, and an optional
+      # name and description that only ever read.
+      name: Nightly, Oslo time
+      description: Fires the day's load once the upstream extract has settled.
+      cron: "0 5 * * *"
+      # The zone belongs to the schedule, not to the host the scheduler happens to run on.
+      # This is five in the morning in Oslo all year, so it stays five in the morning across
+      # a daylight-saving boundary rather than sliding to four or six.
+      timezone: Europe/Oslo
+      # Parameters pinned here override the pipeline's defaults for this schedule's firings
+      # only: environment defaults to staging above, and every nightly firing is production.
+      # A second schedule on the same pipeline pins its own, which is why nightly against
+      # production and hourly against staging is two schedules and not two pipelines.
+      params:
+        day: "2026-01-01"
+        environment: production

dirigent_examples/shelves/triggers/cron-windowed.yaml

@@ -0,0 +1,86 @@
+# The interval a firing covers, rather than the moment it happened at.
+#
+# A schedule answers "when does this start". A window answers "what does this run cover",
+# which is the question a data pipeline actually has: the nightly load at 05:00 is meant to
+# read yesterday, not this instant. Every schedule-fired run carries the interval that just
+# closed -- ${run.window.start} up to but not including ${run.window.end} -- and a step reads
+# it the way it reads a parameter.
+#
+# THE WINDOW IS A PROPERTY OF THE RUN, NOT OF THIS DOCUMENT. Nothing below declares it: the
+# cadence above 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 and quietly asking
+# the upstream system for everything it has:
+#
+#   dg run --local examples/triggers/cron-windowed.yaml --window 2026-06-01..2026-06-02
+#   dg apply examples/triggers/cron-windowed.yaml       # against an instance
+#   dg backfill cron-windowed --schedule nightly \
+#       --from 2026-06-01T05:00:00Z --to 2026-06-08T05:00:00Z --dry-run
+#
+# The window derived from a cron cadence is wall-clock, not a fixed 24 hours: in Europe/Oslo
+# the spring-forward night is 23 hours long and the fall-back night is 25, and the pair of
+# instants below says so honestly rather than rounding it away.
+
+format: dirigent/v1
+kind: pipeline
+code: cron-windowed
+name: Windowed daily load
+description: |
+  A nightly schedule whose runs read the **interval that just closed** rather than
+  the instant they started at.
+
+  `${run.window.start}` and `${run.window.end}` are ISO 8601 instants, half-open:
+  the start is included and the end is not, so two consecutive firings tile the
+  timeline without overlapping or leaving a gap.
+
+tags: [triggers, transform, schedule]
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    dataset:
+      type: string
+      description: Which dataset the load reads, which the schedule pins for every firing.
+      default: cases
+
+steps:
+  # The query a real extractor would be handed. Half-open is the whole point of writing both
+  # ends: `>= from` and `< to` never double-counts a row that lands exactly on a boundary.
+  query:
+    block: transform.jq
+    config:
+      input:
+        dataset: "${params.dataset}"
+        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 belongs to the schedule, so the window it derives is a day of Oslo's clock
+      # and not a fixed number of hours. This is what makes the daylight-saving nights come
+      # out right without anything in the steps below knowing that daylight saving exists.
+      timezone: Europe/Oslo
+      params:
+        dataset: cases

dirigent_examples/shelves/triggers/document-nightly.yaml

@@ -0,0 +1,80 @@
+# Clocks for a pipeline defined somewhere else: the ops team's clock file.
+#
+# A kind: triggers document declares nothing but schedules and webhooks, and names the
+# pipeline they fire. The pipeline itself lives in managed-and-manual.yaml, owned by
+# whoever writes pipelines; this file is owned by whoever decides when they run. Two files,
+# two review cycles, one instance.
+#
+# Applying it does exactly what a pipeline document's triggers: section does, with one
+# difference: the rows it creates are owned by THIS document rather than by the pipeline's.
+# So an apply here creates, redeclares and retires its own schedules and its own webhook,
+# and never touches the two schedules and the webhook managed-and-manual.yaml declares, nor
+# anything an operator made by hand.
+#
+# It refuses three things, and says which at apply:
+#
+#   - a pipeline: that no instance holds, or that is deactivated. Apply the pipeline first;
+#     a directory apply does that for you, because pipelines go before triggers documents.
+#   - a schedule or webhook code the pipeline already carries under a different owner, and
+#     names the owner in the refusal.
+#   - pinned params: the pipeline's current parameter schema would reject, checked here at
+#     apply and again at every firing.
+#
+# Try it against a running instance, in this order:
+#
+#   dg apply examples/triggers/managed-and-manual.yaml   # the pipeline, first
+#   dg apply examples/triggers/document-nightly.yaml     # its clocks, second
+#   dg schedule list managed-and-manual                  # five now: two inline, three here
+#   dg trigger-document show document-nightly            # what this file owns
+#   dg trigger-document delete document-nightly          # its three go; the inline two stay
+#
+# There is nothing to run: this document has no steps. `dg run --local` on it refuses and
+# says to run the pipeline it names.
+
+format: dirigent/v1
+kind: triggers
+code: document-nightly
+name: Nightly batch clocks
+description: Schedules and a webhook for a pipeline another document defines.
+
+pipeline: managed-and-manual
+
+triggers:
+  schedules:
+    # Four in the morning Oslo time, an hour ahead of the pipeline's own nightly schedule:
+    # this is the operations copy that loads yesterday against production, and it is a
+    # separate code so both can exist without either owner editing the other's file.
+    - code: ops-nightly
+      cron: "0 4 * * *"
+      timezone: Europe/Oslo
+      params:
+        day: "2026-01-01"
+        environment: production
+
+    # Monday mornings only, for the weekly reconciliation the same pipeline serves. A cron
+    # expression says this in one line; an interval could not, because a week of hours
+    # drifts across daylight saving and Monday does not.
+    - code: ops-weekly
+      cron: "0 6 * * 1"
+      timezone: Europe/Oslo
+      params:
+        day: "2026-01-01"
+        environment: production
+
+    # A rolling smoke test against staging, on an interval rather than a calendar: nothing
+    # about it needs to land at a particular wall-clock time, and an interval keeps firing
+    # at a fixed spacing however the clocks move.
+    - code: ops-staging-smoke
+      interval: 6h
+      params:
+        day: "2026-01-01"
+        environment: staging
+
+  webhooks:
+    # The operations team's own endpoint, beside the pipeline's. Its token is minted by the
+    # instance and shown once, and deleting this document deletes the endpoint with it --
+    # which is the point of putting it here rather than in the pipeline's own file.
+    - code: ops-manual-kick
+      params_from_payload:
+        day: "$.run.date"
+        environment: "$.run.environment"

dirigent_examples/shelves/triggers/interval-rolling.yaml

@@ -0,0 +1,88 @@
+# A rolling cadence: every hour from whenever it was declared, not at any particular time.
+#
+# The schedule fires only on an instance this document has been applied to. The same
+# document runs ad hoc anywhere, with nothing on the allowlist and no network:
+#
+#   dg run --local examples/triggers/interval-rolling.yaml
+#   dg apply examples/triggers/interval-rolling.yaml   # against an instance
+#   dg schedule list interval-rolling
+#
+# An interval beats a cron when what you want is a cadence -- freshness, a poll, a rolling
+# window -- and nobody cares which minute of the hour it lands on. A cron beats an interval
+# when the firing is a calendar moment someone downstream expects: the nightly load, the
+# Monday report, the close of the month. Write "every 1h" as an interval and "at 05:00 Oslo"
+# as a cron, and neither has to fake the other.
+
+format: dirigent/v1
+kind: pipeline
+code: interval-rolling
+name: A rolling interval
+description: A pipeline on a rolling hourly interval, refreshing a window rather than hitting a calendar moment.
+
+# Two firings of a rolling refresh are not worth having at once: if one is still going when
+# the next hour comes round, skip that firing rather than stack a second run on it.
+
+tags: [triggers, transform, schedule]
+
+concurrency: skip
+
+requires:
+  blocks:
+    - transform.jq
+
+params:
+  type: object
+  properties:
+    window_hours:
+      type: integer
+      default: 24
+      minimum: 1
+      maximum: 168
+    environment:
+      type: string
+      enum: [staging, production]
+      default: staging
+
+steps:
+  window:
+    block: transform.jq
+    config:
+      input:
+        hours: "${params.window_hours}"
+        environment: "${params.environment}"
+      program: |
+        {environment, hours, buckets: [range(0; .hours; 6)]}
+
+  refresh:
+    block: transform.jq
+    depends_on: [window]
+    config:
+      input: "${steps.window.output.value}"
+      program: |
+        {environment, refreshed_hours: .hours, batches: (.buckets | length)}
+
+triggers:
+  schedules:
+    - code: hourly-refresh
+      interval: 1h
+      # A duration is the same length in every zone, so an interval never consults the
+      # calendar and the zone here is read by nothing. It is the cron and at clocks that
+      # need one.
+      timezone: UTC
+      params:
+        window_hours: 24
+        environment: staging
+
+    # The misfire policy is what keeps an hourly schedule from becoming a catchup 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 the 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. A
+    # scheduler down over a weekend therefore wakes up and runs this once, not sixty times.
+    - code: six-hourly-production
+      interval: 6h
+      timezone: UTC
+      params:
+        window_hours: 168
+        environment: production