dirigent-integration 0.27.0__tar.gz → 0.28.0__tar.gz

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: dirigent-integration
-Version: 0.27.0
+Version: 0.28.0
 Summary: The control center for the dirigent plugin ecosystem: assemble every pack, run everyone's tests and examples together.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
-Requires-Dist: dirigent-plugin==0.27.0
+Requires-Dist: dirigent-plugin==0.28.0
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 
@@ -139,15 +139,16 @@ Most of them read a `d2w fhir serve` facade, which publishes one DHIS2 instance
 endpoint and takes captures back; where a general-purpose FHIR server is the point -- an
 `Encounter`, an `Observation`, a `Subscription`, a `_lastUpdated` search, none of which that
 facade serves -- the default is a public HAPI R4 sandbox instead, and the document's header
-says so. Every write is a dry run: `dryRun=true` on `/api/dataValueSets`, `importMode=VALIDATE`
-on `/api/tracker`.
+says so. Every write to DHIS2 is a dry run: `dryRun=true` on `/api/dataValueSets`,
+`importMode=VALIDATE` on `/api/tracker`. The one real write as shipped is
+`dhis2-to-fhir-observations`, which publishes to that public sandbox.
 
 [`examples/fhir/README.md`](examples/fhir/README.md) has the one-line table and the mapping
 vocabulary the shelf is built on -- subject, capture, ConceptMap.
 
 - **`examples/fhir/fhir-capture-bundle-to-data-values.yaml`** -- the capture pair end to end: a page
   of captures pulled off the facade, translated, gated on the pack's own id and period formats,
-  rehearsed and imported.
+  rehearsed and imported, the import a dry run too until `commit_dry_run` is false.
 - **`examples/fhir/fhir-questionnaire-response-to-data-values.yaml`** -- the general case, where a
   `linkId` is a form designer's name and the lookup is the integration.
 - **`examples/fhir/fhir-patient-to-tracked-entity.yaml`** -- the `Patient` register folded into an
@@ -205,7 +206,7 @@ export GITHUB_TOKEN=$(gh auth token)   # only if a component repository is priva
 ### Running the stack
 
 ```sh
-cp .env.example .env      # set DIRIGENT_SECRET_KEY and DIRIGENT_BOOTSTRAP_ADMIN_PASSWORD
+cp .env.example .env      # set DIRIGENT_SECRET_KEY, DIRIGENT_BOOTSTRAP_ADMIN_PASSWORD and POSTGRES_PASSWORD
 make up
 ```
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/README.md

@@ -129,15 +129,16 @@ Most of them read a `d2w fhir serve` facade, which publishes one DHIS2 instance
 endpoint and takes captures back; where a general-purpose FHIR server is the point -- an
 `Encounter`, an `Observation`, a `Subscription`, a `_lastUpdated` search, none of which that
 facade serves -- the default is a public HAPI R4 sandbox instead, and the document's header
-says so. Every write is a dry run: `dryRun=true` on `/api/dataValueSets`, `importMode=VALIDATE`
-on `/api/tracker`.
+says so. Every write to DHIS2 is a dry run: `dryRun=true` on `/api/dataValueSets`,
+`importMode=VALIDATE` on `/api/tracker`. The one real write as shipped is
+`dhis2-to-fhir-observations`, which publishes to that public sandbox.
 
 [`examples/fhir/README.md`](examples/fhir/README.md) has the one-line table and the mapping
 vocabulary the shelf is built on -- subject, capture, ConceptMap.
 
 - **`examples/fhir/fhir-capture-bundle-to-data-values.yaml`** -- the capture pair end to end: a page
   of captures pulled off the facade, translated, gated on the pack's own id and period formats,
-  rehearsed and imported.
+  rehearsed and imported, the import a dry run too until `commit_dry_run` is false.
 - **`examples/fhir/fhir-questionnaire-response-to-data-values.yaml`** -- the general case, where a
   `linkId` is a form designer's name and the lookup is the integration.
 - **`examples/fhir/fhir-patient-to-tracked-entity.yaml`** -- the `Patient` register folded into an
@@ -195,7 +196,7 @@ export GITHUB_TOKEN=$(gh auth token)   # only if a component repository is priva
 ### Running the stack
 
 ```sh
-cp .env.example .env      # set DIRIGENT_SECRET_KEY and DIRIGENT_BOOTSTRAP_ADMIN_PASSWORD
+cp .env.example .env      # set DIRIGENT_SECRET_KEY, DIRIGENT_BOOTSTRAP_ADMIN_PASSWORD and POSTGRES_PASSWORD
 make up
 ```
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "dirigent-integration"
-version = "0.27.0"
+version = "0.28.0"
 description = "The control center for the dirigent plugin ecosystem: assemble every pack, run everyone's tests and examples together."
 readme = "README.md"
 requires-python = ">=3.13"
 license = "LicenseRef-Proprietary"
 license-files = ["LICENSE"]
-dependencies = ["dirigent-plugin==0.27.0"]
+dependencies = ["dirigent-plugin==0.28.0"]
 
 [project.entry-points."dirigent.plugins.v1"]
 integration = "dirigent_integration:plugin"

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-integration"
-version = "0.27.0"
+version = "0.28.0"
 description = "The control center for the dirigent plugin ecosystem: assemble every pack, run everyone's tests and examples together."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -10,7 +10,7 @@ license-files = ["LICENSE"]
 # A published install carries the cross-boundary shelves and nothing else: each document
 # names the packs it needs under requires, and the Examples screen marks what is missing.
 dependencies = [
-    "dirigent-plugin==0.27.0",
+    "dirigent-plugin==0.28.0",
 ]
 
 # dirigent-testing is dev-only: the packs' suites import it, and nothing at runtime does,

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/dhis2-analytics-to-csv-report.yaml

@@ -38,7 +38,10 @@ format: dirigent/v1
 kind: pipeline
 code: dhis2-analytics-to-csv-report
 name: An analytics grid as a csv report
-description: Query DHIS2 analytics, flatten the grid into rows, write a csv to S3, and announce it.
+description: |
+  Turn a DHIS2 analytics query into a csv report in S3 and announce it.
+
+  The analytics grid is flattened into rows before the csv is written.
 
 tags: [dhis2, s3, csv, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/dhis2-export-to-s3.yaml

@@ -24,7 +24,7 @@ format: dirigent/v1
 kind: pipeline
 code: dhis2-export-to-s3
 name: Export a data value set to S3
-description: Read a DHIS2 data value set, write it into object storage, then archive a dated copy.
+description: Export a DHIS2 data value set to object storage and archive a dated copy.
 
 tags: [dhis2, s3, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/dhis2-tracker-weekly-window.yaml

@@ -46,7 +46,7 @@ format: dirigent/v1
 kind: pipeline
 code: dhis2-tracker-weekly-window
 name: A week of tracker events, as parquet
-description: Read the tracker events of the week that just closed and archive them as parquet.
+description: Archive the tracker events of the week that just closed as parquet.
 
 tags: [dhis2, parquet, s3, schedule, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/dhis2-values-per-org-unit-to-parquet.yaml

@@ -9,11 +9,11 @@
 # WHY ONE TABLE AND NOT ONE FILE PER ORG UNIT. A value moves through step outputs, and a value
 # leaves a run through storage.write; a block does not write storage itself. A fan-out step
 # stores one output -- the list of its items' outputs, in item order, with a failed item absent
-# from it -- and `for_each` is expanded when the run is created, so it can read params, run and
-# item and never an upstream step's output. Item three of one step therefore cannot ask item
-# three of another what it produced: a second fan cannot pick up the export its twin made. So
-# the fan-in is a single step over every export, and the org unit is read out of each data
-# value where the join key can be seen, rather than out of a storage path that used to carry it.
+# from it. A second fan could adopt the export's grid with `for_each: ${steps.export.items}` and
+# write one file per org unit, which is what dhis2-export-per-org-unit.yaml in the dhis2 pack
+# does. A query over the whole extraction wants one table, so here the fan-in is a single step
+# over every export, and the org unit is read out of each data value where the join key can be
+# seen, rather than out of a storage path.
 #
 # What happens, hop by hop:
 #
@@ -51,7 +51,11 @@ format: dirigent/v1
 kind: pipeline
 code: dhis2-values-per-org-unit-to-parquet
 name: A parquet table over a batch of org units
-description: Export a data value set per organisation unit, flatten the batch into one parquet table, and manifest what landed.
+description: |
+  Export DHIS2 values per org unit into one parquet table, with a manifest.
+
+  Each organisation unit gets its own data value set export, the batch is flattened into one
+  table, and the manifest says what landed.
 
 tags: [dhis2, parquet, s3, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/dhis2-values-to-parquet.yaml

@@ -21,7 +21,10 @@ format: dirigent/v1
 kind: pipeline
 code: dhis2-values-to-parquet
 name: Export a data value set as parquet
-description: Read a DHIS2 data value set into object storage, then re-encode it as parquet beside it.
+description: |
+  Save a DHIS2 data value set to object storage and convert it to parquet.
+
+  The parquet file is written beside the stored data value set.
 
 tags: [dhis2, parquet, s3, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/README.md

@@ -53,7 +53,7 @@ option set is in the regenerated map, and the pipeline that reads it needs no ed
 
 | File | What it teaches |
 | --- | --- |
-| [fhir-capture-bundle-to-data-values.yaml](fhir-capture-bundle-to-data-values.yaml) | The capture pair end to end: a page of `QuestionnaireResponse` captures pulled off the facade, translated to `/api/dataValueSets`, gated on the pack's `dhis2-uid` and `dhis2-period` formats, rehearsed and then imported. |
+| [fhir-capture-bundle-to-data-values.yaml](fhir-capture-bundle-to-data-values.yaml) | The capture pair end to end: a page of `QuestionnaireResponse` captures pulled off the facade, translated to `/api/dataValueSets`, gated on the pack's `dhis2-uid` and `dhis2-period` formats, rehearsed and then imported, the import a dry run too until `commit_dry_run` is false. |
 | [fhir-questionnaire-response-to-data-values.yaml](fhir-questionnaire-response-to-data-values.yaml) | The general case, where a `linkId` is a form designer's name rather than a DHIS2 uid: an explicit lookup in params, and every unmapped answer counted rather than dropped in silence. |
 | [fhir-patient-to-tracked-entity.yaml](fhir-patient-to-tracked-entity.yaml) | The `Patient` register searched by identifier and folded into an `/api/tracker` registration -- and why the write is an `http.request` on the `dhis2` connection, because `dhis2.tracker` reads and does not write. |
 | [fhir-encounter-to-event.yaml](fhir-encounter-to-event.yaml) | Cardinalities that do not line up: one `Encounter` plus every `Observation` naming it, folded into the single program stage event DHIS2 wants, with the LOINC codes mapped and the rest reported. |

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/dhis2-to-fhir-observations.yaml

@@ -1,7 +1,8 @@
 # The other direction: DHIS2 aggregate values published as a FHIR Bundle of Observations.
 #
 # THE FLOW, END TO END. Export one data value set from DHIS2, turn every data value into an
-# Observation, wrap them in a transaction Bundle, and POST that Bundle to a FHIR server.
+# Observation, wrap them in a transaction Bundle, and POST that Bundle to a FHIR server. As
+# written that server is a public HAPI sandbox, and the POST is real: this one is not a rehearsal.
 #
 # WHY IT IS HERE. Every other document on this shelf reads FHIR and writes DHIS2. This one is
 # the mirror, and a reader who has both in front of them can see what is symmetric and what is
@@ -21,7 +22,8 @@
 # WHAT LEAVES. A transaction Bundle, one entry per data value:
 #
 #   {"resourceType": "Bundle", "type": "transaction",
-#    "entry": [{"request": {"method": "POST", "url": "Observation"},
+#    "entry": [{"request": {"method": "PUT",
+#                           "url": "Observation?identifier=http://dhis2.org/fhir/id/data-value|s46m5MS0hxu.Prlt0C1RF0s-202608-vSbt6cezomG"},
 #               "resource": {
 #                 "resourceType": "Observation", "status": "final",
 #                 "identifier": [{"system": "http://dhis2.org/fhir/id/data-value",
@@ -61,8 +63,10 @@ kind: pipeline
 code: dhis2-to-fhir-observations
 name: DHIS2 data values to FHIR Observations
 description: |
-  Export a DHIS2 data value set and publish it as a transaction `Bundle` of `Observation`
-  resources on a FHIR server.
+  Publish DHIS2 data values to a FHIR server as a bundle of Observations.
+
+  A DHIS2 data value set is exported and published as a transaction `Bundle` of `Observation`
+  resources.
 
   The outbound half of this shelf. Each entry is a conditional update keyed on the aggregate
   cell's natural key -- `(dataElement.categoryOptionCombo, period, orgUnit)` -- so publishing

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-capture-bundle-to-data-values.yaml

@@ -3,7 +3,8 @@
 # THE FLOW, END TO END. `d2w fhir serve` publishes one DHIS2 instance as a FHIR endpoint and
 # takes captures back. This document reads the captures it is holding for one aggregate form,
 # turns them into DHIS2's own `/api/dataValueSets` envelope, gates that envelope on DHIS2's id
-# and period formats, rehearses the import as a dry run, and only then writes it.
+# and period formats, rehearses the import as a dry run, and only then sends it for real -- which
+# is a dry run too until `commit_dry_run` is set to false, because the demo is shared.
 #
 # THE CAPTURE PAIR. The facade's whole capture surface is two resource types, and the pair is
 # the thing to learn:
@@ -54,8 +55,9 @@
 # and a dotted one is one (dataElement, categoryOptionCombo) cell of it.
 #
 # WHERE A READER CHANGES IT. `questionnaire` names the form; on this facade that is a DHIS2
-# data set uid. Point `fhir_base` at your own `d2w fhir serve`, set `questionnaire_uid` to the
-# data set you generated a form from, and repoint the `dhis2` connection.
+# data set uid. Point the `fhir-facade` connection at your own `d2w fhir serve`, set `questionnaire_uid` to the
+# data set you generated a form from, repoint the `dhis2` connection, and turn `commit_dry_run`
+# off against an instance of your own.
 #
 # WHAT THIS DOES NOT DO. It does not invent values for unanswered items -- an absent answer and
 # a zero are different facts -- and it does not register completeness. Completeness is a second
@@ -63,15 +65,19 @@
 # values rather than accompany them.
 #
 #   dg run --local examples/fhir/fhir-capture-bundle-to-data-values.yaml
-#   dg run --local examples/fhir/fhir-capture-bundle-to-data-values.yaml -p fhir_base=http://localhost:8096
+#   dg run --local examples/fhir/fhir-capture-bundle-to-data-values.yaml -p page_size=10
 
 format: dirigent/v1
 kind: pipeline
 code: fhir-capture-bundle-to-data-values
 name: FHIR captures to DHIS2 data values
 description: |
-  Read a page of `QuestionnaireResponse` captures off a `d2w fhir serve` facade and import
-  them into DHIS2 as aggregate data values, rehearsing the import first.
+  Import the first completed FHIR form response on a page into DHIS2.
+
+  A page of `QuestionnaireResponse` captures is read off a `d2w fhir serve` facade. The first
+  completed one becomes aggregate data values, and the import is rehearsed first.
+  `commit_dry_run` defaults to true, so the second import is a rehearsal too until it is set to
+  false against an instance of your own.
 
   The capture pair is the vocabulary: a `Questionnaire` is the form definition generated from
   DHIS2 metadata, and a `QuestionnaireResponse` is one submission against it. Every `linkId`
@@ -95,8 +101,9 @@ connections:
     config:
       base_url: http://localhost:8095
       timeout: 30s
-  # The instance the values land in. This is the demo, which is for reading: the import below
-  # is a dry run against it, and repointing this connection is what makes the real one real.
+  # The instance the values land in. This is the demo, which is for reading: both imports below
+  # are dry runs against it, and repointing this connection and setting commit_dry_run to false
+  # is what makes the real one real.
   dhis2-demo:
     kind: dhis2
     config:
@@ -108,10 +115,6 @@ connections:
 params:
   type: object
   properties:
-    fhir_base:
-      type: string
-      description: The facade to read captures from.
-      default: http://localhost:8095
     questionnaire_uid:
       type: string
       description: The aggregate form, which on this facade is the DHIS2 data set uid.
@@ -120,6 +123,10 @@ params:
       type: integer
       description: How many captures one page holds; the facade caps this at 500.
       default: 50
+    commit_dry_run:
+      type: boolean
+      description: Whether the second import is still a rehearsal. False makes it real.
+      default: true
 
 schemas:
   # The gate is the pack's own formats, not a shape check: dhis2-uid refuses anything that is
@@ -219,12 +226,13 @@ steps:
 
   # Second, and only because the rehearsal passed. The default all_success edge is what
   # enforces that: a refused rehearsal leaves this skipped rather than writing anyway.
+  # commit_dry_run keeps this a rehearsal as well, so the shared demo is never written to.
   import:
     block: dhis2.data_value_set_import
     depends_on: [rehearse]
     config:
       connection: dhis2-demo
       data_values: "${steps.gate.output.value}"
-      dry_run: false
+      dry_run: "${params.commit_dry_run}"
       import_strategy: CREATE_AND_UPDATE
       atomic_mode: ALL

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-conceptmap-driven-mapping.yaml

@@ -60,8 +60,11 @@ kind: pipeline
 code: fhir-conceptmap-driven-mapping
 name: A ConceptMap drives the mapping
 description: |
-  Fetch a `ConceptMap` from the FHIR server, flatten it into a lookup, and translate a
-  capture's coded answers through it -- so no code appears in this document at all.
+  Fetch a code mapping from a FHIR server and use it to translate form answers.
+
+  A `ConceptMap` is flattened into a lookup and a capture's coded answers are translated through
+  it, so the mapping itself is not written in this document. The translated set goes to DHIS2 as
+  a dry run.
 
   A `d2w fhir serve` option-set map carries two groups distinguished by `group.target`: one to
   the DHIS2 option uid (always complete) and one to the DHIS2 option code (only where the

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-encounter-to-event.yaml

@@ -8,7 +8,7 @@
 # DHIS2 as forms and captures, so its whole clinical surface is the capture pair, and asking
 # it for an Observation answers an OperationOutcome with code `not-supported`. Encounters come
 # from the other kind of FHIR server: a hospital's own, an OpenMRS, a HAPI. That is the point
-# of this example, so `fhir_base` defaults to the public HAPI R4 test server. It is a shared
+# of this example, so the `fhir-clinical` connection points at the public HAPI R4 test server. It is a shared
 # sandbox anyone can write to, so the resources it holds change under you; every id below is a
 # parameter for that reason, and the searches are written to survive not finding one.
 #
@@ -51,11 +51,11 @@
 # each entry is one LOINC code and the DHIS2 data element uid it lands in. The stage the event
 # belongs to is `program_stage`, and the program and enrollment are `program` and
 # `enrollment_uid`. An observation whose LOINC code is not in the table is dropped and counted
-# -- conceptmap-driven-mapping.yaml is the same mapping fetched from a server instead.
+# -- fhir-conceptmap-driven-mapping.yaml is the same mapping fetched from a server instead.
 #
 # WHAT THIS DOES NOT DO. It does not resolve the Encounter's Patient to a DHIS2 tracked entity.
-# That is a real lookup against a real identifier crosswalk, and patient-to-tracked-entity.yaml
-# is the half that does it; here the entity and its enrollment are parameters.
+# That is a real lookup against a real identifier crosswalk, and
+# fhir-patient-to-tracked-entity.yaml is the half that does it; here the entity and its enrollment are parameters.
 #
 #   dg run --local examples/fhir/fhir-encounter-to-event.yaml
 #   dg run --local examples/fhir/fhir-encounter-to-event.yaml -p encounter_id=137202491
@@ -65,7 +65,9 @@ kind: pipeline
 code: fhir-encounter-to-event
 name: Encounter and Observations to one event
 description: |
-  Fold one FHIR `Encounter` and every `Observation` naming it into a single DHIS2 tracker
+  Turn one FHIR visit and its measurements into one DHIS2 event, as a dry run.
+
+  One FHIR `Encounter` and every `Observation` naming it are folded into a single DHIS2 tracker
   event, posted with `importMode=VALIDATE`.
 
   The cardinalities do not line up: FHIR spreads a visit over an Encounter plus one
@@ -119,7 +121,7 @@ params:
     tracked_entity:
       type: string
       description: The DHIS2 person the Encounter's Patient resolves to. A real crosswalk is
-        patient-to-tracked-entity.yaml.
+        fhir-patient-to-tracked-entity.yaml.
       default: coxwIkMqNBB
     enrollment_uid:
       type: string

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-measure-report-to-analytics-check.yaml

@@ -15,7 +15,8 @@
 # population, Denominator, Denominator exclusion, Numerator, Numerator exclusion) -- over a
 # Bundle of FHIR data, and a measure evaluation engine is what turns that scoring into an R4
 # MeasureReport. The report is then a resource like any other, so this document fetches it
-# from wherever it was published. `fhir_base` defaults to a public HAPI R4 sandbox.
+# from wherever it was published. The `fhir-reports` connection points at a public HAPI R4
+# sandbox by default.
 #
 # WHAT ARRIVES -- the report. A proportion measure scored over a period:
 #
@@ -40,12 +41,15 @@
 # checked and they agree" is a fact worth delivering too:
 #
 #   {"measure": "...", "period": "202608", "org_unit": "ImspTQPwCqd",
-#    "fhir_score": 0.75, "dhis2_value": 0.71, "difference": 0.04, "discrepant": true}
+#    "report_period": {"start": "2026-08-01", "end": "2026-08-31"},
+#    "fhir_score": 0.75, "dhis2_value": 0.71, "difference": 0.04, "verdict": "discrepant"}
 #
 # WHICH CODES LINE UP WITH WHAT. `measure_url` and `indicator` are the two halves of one claim
 # -- that this FHIR measure and this DHIS2 data element or indicator count the same thing --
-# and a reader changes both together or neither. `period` is a DHIS2 ISO period; the FHIR side
-# carries a date range, so the two are matched on the range the period covers.
+# and a reader changes both together or neither. `period` and `report_period` are the same
+# stretch of time in two vocabularies, and they change together too: `period` is a DHIS2 ISO
+# period, and `report_period` a FHIR date, whose search matches a report inside that range. The
+# record carries the range the report named, so a reader can see what was compared.
 #
 # WHEN IT FINDS NOTHING. A missing report and an empty grid are ordinary answers, not failures:
 # the diff says `unavailable` and the receiver hears about it. A reconciliation that crashed
@@ -59,8 +63,10 @@ kind: pipeline
 code: fhir-measure-report-to-analytics-check
 name: MeasureReport against DHIS2 analytics
 description: |
-  Hold a FHIR `MeasureReport` against the DHIS2 analytics value for the same period and org
-  unit, and deliver the gap.
+  Compare a FHIR measure report with DHIS2 analytics and report the difference.
+
+  The newest FHIR `MeasureReport` for the measure and period is held against the DHIS2 analytics
+  value for that period and one org unit, and the gap is delivered.
 
   A reconciliation, so it writes nothing: safe on a schedule. The report is produced by
   scoring a CQL measure over FHIR data -- `d2w fhir serve` publishes no `Measure` or
@@ -114,8 +120,12 @@ params:
       default: ImspTQPwCqd
     period:
       type: string
-      description: A DHIS2 ISO period; the FHIR side is matched on the range it covers.
+      description: The DHIS2 ISO period analytics is asked for.
       default: "202608"
+    report_period:
+      type: string
+      description: The same period as a FHIR date, which the report search matches within.
+      default: "2026-08"
     tolerance:
       type: number
       description: How far apart the two may be before the difference is called a discrepancy.
@@ -133,6 +143,7 @@ steps:
       method: GET
       query:
         measure: "${params.measure_url}"
+        period: "${params.report_period}"
         _sort: "-date"
         _count: 1
       headers:
@@ -181,6 +192,7 @@ steps:
         | {measure: $measure,
            period: $period,
            org_unit: $org_unit,
+           report_period: $report.period,
            fhir_score: $score,
            dhis2_value: $value,
            populations: [(($report.group[0].population // [])[])

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-nightly-window-sync.yaml

@@ -51,6 +51,12 @@
 # first page and reports whether there were more, which is the smallest thing that does not
 # quietly lie about completeness.
 #
+# WHERE THIS GOES NEXT. The sync exists to feed DHIS2, and the shelf's other documents are what
+# turn each of these types into an import: Patient through fhir-patient-to-tracked-entity.yaml,
+# Encounter through fhir-encounter-to-event.yaml, QuestionnaireResponse through
+# fhir-capture-bundle-to-data-values.yaml. This one only pulls, and its last step only asks the
+# instance they import into whether it answers.
+#
 # WHERE A READER CHANGES IT. `resource_types` is the fan-out and the whole scope of the sync;
 # `page_size` is what one page holds. Add a type to the list and the grid grows on the next
 # firing with nothing else edited.
@@ -65,8 +71,11 @@ kind: pipeline
 code: fhir-nightly-window-sync
 name: Nightly windowed FHIR sync
 description: |
-  Pull everything a FHIR server changed inside the interval a nightly schedule just closed,
-  one fan-out item per resource type, and join the results into one summary.
+  Pull last night's changes from a FHIR server, type by type, into one summary.
+
+  Each run reads what changed inside the interval the nightly schedule just closed, with one
+  fan-out item per resource type, and joins the results. Only the first page of each type is
+  read, and the summary says whether more were left.
 
   The window belongs to the run, not to this document: `${run.window.start}` and
   `${run.window.end}` are half-open ISO instants, so consecutive firings tile the timeline
@@ -80,17 +89,7 @@ requires:
     - transform.jq
 
 connections:
-  # Carried for its timeout and TLS setting; the searches below give absolute URLs, because a
-  # half-open range needs the same query parameter twice and the query map holds one per key.
-  fhir-source:
-    kind: http
-    config:
-      base_url: https://hapi.fhir.org/baseR4
-      timeout: 60s
-  # Not read by this document, which only pulls. It is here because the sync exists to feed
-  # DHIS2, and the shelf's other documents are what turn each of these types into an import:
-  # Patient through patient-to-tracked-entity.yaml, Encounter through encounter-to-event.yaml,
-  # QuestionnaireResponse through capture-bundle-to-data-values.yaml.
+  # The instance this sync feeds, read by the target step and written by nothing here.
   dhis2-demo:
     kind: dhis2
     config:
@@ -119,10 +118,9 @@ params:
       default: 50
 
 steps:
-  # for_each is expanded when the run is created, so it reads params, run and item -- never
-  # another step's output, because the cardinality of the grid has to be known before anything
-  # executes. That is why the types are a parameter and not something discovered from
-  # /metadata: a run's shape is fixed before its first request.
+  # for_each reads a parameter here, so the grid is written when the run is created. It could
+  # read a step's output, and discover the types from /metadata, but then the grid would not
+  # exist until that step settled. A parameter fixes the run's shape before its first request.
   pull:
     block: http.request
     for_each: "${params.resource_types}"
@@ -130,6 +128,7 @@ steps:
     config:
       url: "${params.fhir_base}/${item}?_lastUpdated=ge${run.window.start}&_lastUpdated=lt${run.window.end}&_count=${params.page_size}&_sort=_lastUpdated"
       method: GET
+      timeout: 60s
       headers:
         Accept: application/fhir+json
       # A type this server does not serve answers 404 or an OperationOutcome, and under
@@ -170,6 +169,17 @@ steps:
            # what keeps a partial sync from reading like a complete one.
            types_missed: ($asked - [$seen[] | .type])}
 
+  # One short read of the instance the types above are imported into. Tolerated, because a
+  # sleeping DHIS2 does not change what the FHIR server said.
+  target:
+    block: http.request
+    depends_on: [summarise]
+    continue_on_failure: true
+    config:
+      connection: dhis2-demo
+      path: /api/system/info
+      method: GET
+
 triggers:
   schedules:
     - code: nightly

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-patient-to-tracked-entity.yaml

@@ -69,8 +69,10 @@ kind: pipeline
 code: fhir-patient-to-tracked-entity
 name: FHIR Patient to a DHIS2 tracked entity
 description: |
-  Search the facade's `Patient` register and build the `/api/tracker` payload for one tracked
-  entity and its enrollment, posted with `importMode=VALIDATE`.
+  Turn a FHIR Patient into a DHIS2 tracked entity and enrollment, as a dry run.
+
+  The run searches the facade's `Patient` register and builds the `/api/tracker` payload for one
+  tracked entity and its enrollment, posted with `importMode=VALIDATE`.
 
   `dhis2.tracker` reads and does not write, so the write is an ordinary `http.request` on the
   `dhis2` connection -- which works because the HTTP blocks read `base_url` and the basic

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-questionnaire-response-to-data-values.yaml

@@ -1,14 +1,15 @@
 # One QuestionnaireResponse mapped onto data elements by a linkId lookup the document carries.
 #
-# THE FLOW, END TO END. Read one capture off the facade by its receipt id, translate its
-# answers into data values through an explicit linkId-to-data-element table held in params,
-# and import the result -- dry run first.
+# THE FLOW, END TO END. Take one capture, written inline, translate its answers into data
+# values through an explicit linkId-to-data-element table held in params, and rehearse the
+# import as a dry run. It writes nothing, here or on any instance, until the rehearse step's
+# dry_run is turned off.
 #
 # WHY A LOOKUP AT ALL. On a `d2w fhir serve` facade the linkIds already ARE DHIS2 uids, so
-# capture-bundle-to-data-values.yaml needs no table: it splits the dotted linkId and is done.
+# fhir-capture-bundle-to-data-values.yaml needs no table: it splits the dotted linkId and is done.
 # Every other FHIR server in the world uses linkIds a form designer chose -- "anc.visits.total",
 # "q3b", "weight_kg" -- and then the table IS the integration. This document is the general
-# case, and the facade is only where the example gets a real response to run against.
+# case, and the inline response stands in for what such a server sends.
 #
 # WHAT ARRIVES. One QuestionnaireResponse, answers keyed by whatever the form calls them:
 #
@@ -38,8 +39,10 @@ kind: pipeline
 code: fhir-questionnaire-response-to-data-values
 name: QuestionnaireResponse through a linkId table
 description: |
-  Map one `QuestionnaireResponse` onto DHIS2 data values through an explicit linkId lookup,
-  for the general case where a form's `linkId` is a designer's name rather than a DHIS2 uid.
+  Map one FHIR form response onto DHIS2 data values using a lookup table.
+
+  The `QuestionnaireResponse` goes through an explicit linkId lookup, for the general case where
+  a form's `linkId` is a designer's name rather than a DHIS2 uid. The import is a dry run.
 
   A linkId the table does not name is dropped and counted, never guessed at.
 
@@ -94,7 +97,7 @@ params:
 steps:
   # The capture, written inline so the document runs with nothing set up. In service it is the
   # body of an endpoint delivery (fhir-subscription-to-dhis2.yaml) or one entry of a
-  # searchset Bundle (capture-bundle-to-data-values.yaml); either way this step's output is
+  # searchset Bundle (fhir-capture-bundle-to-data-values.yaml); either way this step's output is
   # exactly one QuestionnaireResponse, and nothing downstream knows where it came from.
   receive:
     block: value.const

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/fhir/fhir-subscription-to-dhis2.yaml

@@ -94,8 +94,11 @@ kind: pipeline
 code: fhir-subscription-to-dhis2
 name: A FHIR Subscription notification imported
 description: |
-  Take a FHIR `Subscription` rest-hook notification on an endpoint source, translate the
-  notified `QuestionnaireResponse` into a DHIS2 data value set, and rehearse the import.
+  Receive a FHIR notification and rehearse importing it into DHIS2.
+
+  A FHIR `Subscription` rest-hook notification arrives on an endpoint source, and the notified
+  `QuestionnaireResponse` is translated into a DHIS2 data value set before the import is
+  rehearsed.
 
   The subscription contract is three fields: `criteria` (a search string), `channel.type`
   (`rest-hook` is an HTTP POST), and `channel.endpoint` (the source's route). The server

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/README.md

@@ -24,7 +24,7 @@ setting (`storage_connections: {s3: <code>}`); the rest need only a network.
 | --- | --- |
 | [`http-json-to-data-values.yaml`](http-json-to-data-values.yaml) | The shortest inbound path: pull a public JSON API, reshape it, gate it on DHIS2's own id and period formats, import it as a dry run. |
 | [`csv-drop-to-data-values.yaml`](csv-drop-to-data-values.yaml) | The file drop: wait for a csv to land in a bucket, decode it, translate the sender's codes to uids through a lookup, drop the rows that carry no measurement. |
-| [`endpoint-payload-to-tracker-event.yaml`](endpoint-payload-to-tracker-event.yaml) | Push instead of poll: an endpoint source takes one posted encounter, and the jq step that picks its named fields is the whole security boundary. |
+| [`endpoint-payload-to-data-values.yaml`](endpoint-payload-to-data-values.yaml) | Push instead of poll: an endpoint source takes one posted encounter, and the jq step that picks its named fields is the whole security boundary. |
 | [`parquet-lakehouse-to-dhis2.yaml`](parquet-lakehouse-to-dhis2.yaml) | Grain: a parquet table of encounter-level rows reduced to the figures DHIS2 stores, then a completeness sensor that observes rather than registers. |
 | [`fhir-observations-to-data-values.yaml`](fhir-observations-to-data-values.yaml) | Two standards meeting: LOINC codes mapped onto data elements, instants truncated to periods, and the org unit the payload cannot supply. |
 | [`weekly-window-pull-and-import.yaml`](weekly-window-pull-and-import.yaml) | The window: a schedule whose runs pull the week that closed, `${run.window.start}` to `${run.window.end}`, so a late run and a backfill read the same week. |

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/csv-drop-to-data-values.yaml

@@ -39,8 +39,11 @@ kind: pipeline
 code: csv-drop-to-data-values
 name: A csv drop into DHIS2
 description: |
-  Wait for a csv to land in object storage, decode it, translate the sender's codes into
-  DHIS2 uids, drop the rows that carry no measurement, and import what is left.
+  Wait for a csv in object storage and import its rows into DHIS2.
+
+  The csv is decoded, the sender's codes are translated into DHIS2 uids, the rows that carry no
+  measurement are dropped, and what is left is imported. `dry_run` defaults to true, so a first
+  run writes nothing.
 
 tags: [inbound, dhis2, storage, transform, cross-boundary]
 

dirigent_integration-0.27.0/src/dirigent_integration/shelves/inbound/endpoint-payload-to-tracker-event.yaml → dirigent_integration-0.28.0/src/dirigent_integration/shelves/inbound/endpoint-payload-to-data-values.yaml

@@ -34,20 +34,20 @@
 #
 # RUN IT BY HAND, here, with no server. No --input takes the source's sample:
 #
-#   dg run --local examples/inbound/endpoint-payload-to-tracker-event.yaml
-#   dg run --local examples/inbound/endpoint-payload-to-tracker-event.yaml --input '{body: {
+#   dg run --local examples/inbound/endpoint-payload-to-data-values.yaml
+#   dg run --local examples/inbound/endpoint-payload-to-data-values.yaml --input '{body: {
 #     encounter: {facility: DiszpKrYNg8, occurred_at: "2026-06-14T09:20:00Z",
 #     items: [{code: NVP_WITHIN_72H, quantity: 3}]}}}'
 #
 # ON A SERVER, apply it, keep the token the apply printed, and post an encounter:
 #
-#   dg apply examples/inbound/endpoint-payload-to-tracker-event.yaml
-#   dg source call endpoint-payload-to-tracker-event posted --source-token "$TOKEN" --body '{
+#   dg apply examples/inbound/endpoint-payload-to-data-values.yaml
+#   dg source call endpoint-payload-to-data-values posted --source-token "$TOKEN" --body '{
 #     "encounter": {"facility": "DiszpKrYNg8", "occurred_at": "2026-06-14T09:20:00Z",
 #     "items": [{"code": "EXPOSED_REGISTERED", "quantity": 2}]}}'
 #   curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
 #     --data @encounter.json http://localhost:3333/endpoints/captures
-#   dg source inputs endpoint-payload-to-tracker-event posted
+#   dg source inputs endpoint-payload-to-data-values posted
 #
 # The token lives on the instance and is shown once; `dg source rotate-token` mints another.
 #
@@ -55,11 +55,14 @@
 
 format: dirigent/v1
 kind: pipeline
-code: endpoint-payload-to-tracker-event
+code: endpoint-payload-to-data-values
 name: A pushed encounter into DHIS2
 description: |
+  Take an encounter posted by an outside system and import it into DHIS2.
+
   An outside system POSTs one captured encounter to an endpoint source; a jq step picks the
-  named fields, and the run reshapes them into a DHIS2 data value set and imports it.
+  named fields, and the run reshapes them into a DHIS2 data value set and imports it. `dry_run`
+  defaults to true, so a first run writes nothing.
 
   The pack's `dhis2.tracker` block reads `/api/tracker` and does not write it, so an
   event-shaped capture lands as the aggregate figures it contributes to.

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/fan-out-per-facility-import.yaml

@@ -6,10 +6,9 @@
 #
 # WHY THE FAN CONVERGES AT THE IMPORT. Two reasons, and both are worth knowing:
 #
-#   for_each is expanded when the run is created, so it may read params, run and item but
-#   never another step's output: the cardinality has to exist before anything executes. A
-#   step fanned over "the facilities that answered" is therefore not expressible, and
-#   should not be -- it would make the shape of the run depend on the weather.
+#   A for_each may read another step's output, so a step fanned over "the facilities that
+#   answered" could be written. It should not be: it would make the shape of the run depend
+#   on the weather, and its grid would not exist until the pull had settled.
 #
 #   A data value set carries orgUnit per value, so one document can hold every facility at
 #   once. Fifteen imports of one facility each would be fifteen round trips, fifteen
@@ -50,8 +49,11 @@ kind: pipeline
 code: fan-out-per-facility-import
 name: A facility fan-out into one district import
 description: |
-  Pull one facility at a time, tolerate the ones that are down, import what answered as a
-  single data value set, and post a reconciliation of asked-for against imported.
+  Collect from each facility, import what answered, and report who did not.
+
+  There is one pull per facility, tolerating the ones that are down. What answered is imported as
+  a single data value set, and a reconciliation of asked-for against imported is posted. `dry_run`
+  defaults to true, so a first run writes nothing.
 
 tags: [inbound, dhis2, http, graph, transform, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/fhir-observations-to-data-values.yaml

@@ -18,9 +18,9 @@
 # The hops, and the shape at each one:
 #
 #   1. pull       -> a FHIR Bundle: {resourceType: "Bundle", entry: [{resource: {...}}]}
-#   2. flatten    -> one row per entry that has both a mapped LOINC code and a numeric
-#                    value; everything else is dropped, silently and on purpose
-#   3. aggregate  -> {dataValues: [...]}, one value per (element, period) pair, summed
+#   2. flatten    -> one row per entry that has both a mapped LOINC code and a time it
+#                    happened; everything else is dropped, silently and on purpose
+#   3. aggregate  -> {dataValues: [...]}, one value per (element, period) pair, counted
 #   4. gate       -> refused unless the ids and periods are DHIS2's own
 #   5. import     -> the instance's summary
 #
@@ -34,8 +34,8 @@
 # perfectly predictable in shape -- which is the half this example teaches. If a run finds
 # nothing mappable, the gate refuses an empty set rather than importing nothing quietly.
 #
-# What makes it yours: fhir_base_url pointed at your server, the lookup table, and the
-# org unit.
+# What makes it yours: the `fhir-server` connection pointed at your server, the lookup table,
+# and the org unit.
 #
 #   dg run --local examples/inbound/fhir-observations-to-data-values.yaml
 #   dg run --local examples/inbound/fhir-observations-to-data-values.yaml -p count=50
@@ -45,8 +45,11 @@ kind: pipeline
 code: fhir-observations-to-data-values
 name: FHIR Observations into DHIS2
 description: |
-  Pull a FHIR Observation bundle, map LOINC codes onto DHIS2 data elements, reduce the
-  observations to monthly counts, and import them as a data value set.
+  Count FHIR Observations by month and import the counts into DHIS2.
+
+  A FHIR Observation bundle is pulled, LOINC codes are mapped onto DHIS2 data elements, and the
+  monthly counts are imported as a data value set. `dry_run` defaults to true, so a first run
+  writes nothing.
 
 tags: [inbound, dhis2, http, transform, validate, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/http-json-to-data-values.yaml

@@ -27,15 +27,18 @@
 # write nothing. The play server is shared, so leave it true there.
 #
 #   dg run --local examples/inbound/http-json-to-data-values.yaml
-#   dg run --local examples/inbound/http-json-to-data-values.yaml -p country=NGA
+#   dg run --local examples/inbound/http-json-to-data-values.yaml \
+#     -p source_url=https://api.worldbank.org/v2/country/NGA/indicator/SP.POP.TOTL
 
 format: dirigent/v1
 kind: pipeline
 code: http-json-to-data-values
 name: A public JSON API into DHIS2
 description: |
-  Pull a public JSON feed, reshape it into a DHIS2 data value set, gate it on DHIS2's own
-  id and period formats, and hand it to `dhis2.data_value_set_import` as a dry run.
+  Pull a public JSON feed and rehearse importing it into DHIS2.
+
+  The feed is reshaped into a DHIS2 data value set, gated on DHIS2's own id and period formats,
+  and handed to `dhis2.data_value_set_import` as a dry run.
 
 tags: [inbound, dhis2, http, transform, validate, cross-boundary]
 
@@ -62,10 +65,6 @@ params:
       type: string
       description: The outside feed. Anything answering JSON works; the reshape is what changes.
       default: https://api.worldbank.org/v2/country/SLE/indicator/SP.POP.TOTL
-    country:
-      type: string
-      description: The ISO3 code spliced into source_url when it is left at its default.
-      default: SLE
     data_element:
       type: string
       description: The uid every pulled observation lands on; Total Population, yearly.

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/outside-to-dhis2-with-checks.yaml

@@ -40,16 +40,19 @@
 # becomes real by setting it false against an instance of your own.
 #
 #   dg run --local examples/inbound/outside-to-dhis2-with-checks.yaml
-#   dg run --local examples/inbound/outside-to-dhis2-with-checks.yaml -p commit_dry_run=false
+#   dg run --local examples/inbound/outside-to-dhis2-with-checks.yaml -p commit_dry_run=false   # against your own instance
 
 format: dirigent/v1
 kind: pipeline
 code: outside-to-dhis2-with-checks
 name: An inbound pipeline with every guard
 description: |
+  Import outside data into DHIS2 with a safety check at every stage.
+
   A readiness sensor, a schema on what arrived, a schema on what was built, a rehearsed
   import, the real import behind it, and the completeness sensor -- each guard buying off a
-  different failure.
+  different failure. `commit_dry_run` defaults to true, so the second import is a rehearsal too
+  until it is set to false.
 
 tags: [inbound, dhis2, http, sensor, transform, validate, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/parquet-lakehouse-to-dhis2.yaml

@@ -41,8 +41,11 @@ kind: pipeline
 code: parquet-lakehouse-to-dhis2
 name: A lakehouse table into DHIS2
 description: |
-  Read a parquet export of encounter-grain rows, aggregate it to DHIS2's grain, import it,
-  and wait for the month to be signed off.
+  Sum a parquet export down to DHIS2 figures, import them, and await sign-off.
+
+  The parquet export holds encounter-grain rows, which are aggregated to DHIS2's grain before the
+  import, and the run then waits for the month to be signed off. `dry_run` defaults to true, so a
+  first run writes nothing.
 
 tags: [inbound, dhis2, parquet, storage, transform, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/inbound/weekly-window-pull-and-import.yaml

@@ -42,9 +42,11 @@ kind: pipeline
 code: weekly-window-pull-and-import
 name: A weekly windowed pull into DHIS2
 description: |
-  A Monday schedule whose runs pull the week that just closed -- `${run.window.start}` up
-  to but not including `${run.window.end}` -- reshape it into a data value set, import it,
-  and wait for the week to be signed off.
+  Pull last week's data every Monday, import it into DHIS2, and await sign-off.
+
+  A Monday schedule's runs pull the week that just closed -- `${run.window.start}` up to but not
+  including `${run.window.end}` -- reshape it into a data value set, import it, and wait for the
+  week to be signed off. `dry_run` defaults to true, so a first run writes nothing.
 
 tags: [inbound, dhis2, http, schedule, transform, cross-boundary]
 

{dirigent_integration-0.27.0 → dirigent_integration-0.28.0}/src/dirigent_integration/shelves/parquet-to-dhis2-import.yaml

@@ -41,7 +41,7 @@
 # (storage_connections: {s3: <code>}).
 #
 #   dg run --local examples/parquet-to-dhis2-import.yaml
-#   dg run --local examples/parquet-to-dhis2-import.yaml -p dry_run=false
+#   dg run --local examples/parquet-to-dhis2-import.yaml -p dry_run=false   # against your own instance
 
 format: dirigent/v1
 kind: pipeline