From 6b5e9db2e2cd59b5ed4fbc67e62d56eb56f8410b Mon Sep 17 00:00:00 2001 From: abrichr Date: Tue, 21 Jul 2026 01:56:45 -0400 Subject: [PATCH] docs(readme): add a data-driven loop program graph beside the linear one The README showed only the linear MockMed program graph. Add a second, richer example right after it: a compact `save-encounter` body wrapped by `openadapt flow for-each` into a governed data-driven LOOP, rendered by `openadapt flow visualize --format mermaid`. The graph shows the `Loop over worklist` node running the body once per record (`per row of worklist`), the `next record` loop-back edge, the `worklist exhausted` exit to `Success`, and the irreversible, effect-verified `save encounter` write as the per-record halt point. A plain-text caption carries the same content for PyPI (no Mermaid there). The graph is engine-generated (not hand-drawn) and the loop it depicts is replay-tested in openadapt-flow. Honest about scope: identity gating is noted as "where armed", and the body is labelled a compact MockMed fixture with a pointer to the full-recording loop showcase. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index f2b6a7130..369e0773d 100644 --- a/README.md +++ b/README.md @@ -244,6 +244,44 @@ ending in a `Success` terminal.* The `--format html` render is a self-contained, offline page with the full per-step resolution ladder, identity, and effect annotations; `--format json` emits the shared graph spec. +A compiled program is not limited to a straight line. Wrapping a demonstrated +body in `openadapt flow for-each` compiles a **data-driven loop**, and +`visualize` renders that richer structure honestly. Here is a compact +`save-encounter` body wrapped in a governed loop over a worklist, generated by +`openadapt flow visualize bundle --format mermaid` (again, not drawn by hand): + +```mermaid +flowchart TD + n0{"Loop over worklist"} + n1("type ") + n2("type ") + n3("save encounter
effect ยท irreversible") + n4{{"Success"}} + n0 -->|per row of worklist| n1 + n1 --> n2 + n2 --> n3 + n3 -->|next record| n0 + n0 -->|worklist exhausted| n4 + classDef irreversible stroke:#b4530a,stroke-width:2px; + classDef halt stroke:#b21f2d,stroke-width:2px; + class n3 irreversible; + class n3 halt; +``` + +*Text summary (PyPI does not render Mermaid): a governed loop over a worklist. +The `Loop over worklist` node runs the demonstrated body once per record (`per +row of worklist`): type the `patient_id`, type the `note`, then the `save +encounter` write, which is marked **irreversible**, **effect-verified** against +the system of record, and the per-record halt point. Control returns to the loop +(`next record`) after each record and leaves to `Success` only when the worklist +is exhausted; a record whose write cannot be verified halts the run instead of +being skipped.* Every per-record gate the linear replay applies -- identity +where armed, effect verification, and postconditions -- fires again on each +iteration, bounded so an over-long worklist halts rather than running unbounded. +The body shown is a compact MockMed fixture whose loop is replay-tested in +`openadapt-flow`; a loop authored over a full recording is in that repo's +`docs/showcase-loop`. + Replayed locally, that same compiled workflow runs deterministically with no model calls. The optional desktop app (**Experimental**) shows a completed run: 11/11 steps verified, and `$0.000` because a healthy run makes no model calls: