plexus-python-pulse-demeter 1.1.131__tar.gz → 1.1.133__tar.gz

{plexus_python_pulse_demeter-1.1.131 → plexus_python_pulse_demeter-1.1.133}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python-pulse-demeter
-Version: 1.1.131
+Version: 1.1.133
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -15,7 +15,7 @@ Requires-Dist: textcase
 Requires-Dist: plexus-python-common[all]>=1.1
 Requires-Dist: plexus-python-pulse-common[all]>=1.1
 Provides-Extra: all
-Requires-Dist: plexus-python-pulse-demeter[api,cli]; extra == "all"
+Requires-Dist: plexus-python-pulse-demeter[api,cli,workflow]; extra == "all"
 Provides-Extra: api
 Requires-Dist: alembic; extra == "api"
 Requires-Dist: fastapi; extra == "api"
@@ -26,6 +26,9 @@ Requires-Dist: ujson; extra == "api"
 Requires-Dist: uvicorn; extra == "api"
 Provides-Extra: cli
 Requires-Dist: argcomplete; extra == "cli"
+Provides-Extra: workflow
+Requires-Dist: requests>=2.32; extra == "workflow"
+Requires-Dist: pydantic>=2.11; extra == "workflow"
 Provides-Extra: test
 Requires-Dist: ddt>=1.7; extra == "test"
 Requires-Dist: moto[s3,server]>=5.1; extra == "test"
@@ -33,4 +36,4 @@ Requires-Dist: pytest-cov>=5.0; extra == "test"
 Requires-Dist: pytest-httpx2>=1.0; extra == "test"
 Requires-Dist: pytest-order>=1.3; extra == "test"
 Requires-Dist: pytest-postgresql>=6.1; extra == "test"
-Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest>=9.2; extra == "test"

{plexus_python_pulse_demeter-1.1.131 → plexus_python_pulse_demeter-1.1.133}/README.md

@@ -80,5 +80,5 @@ kubectl create secret generic plexus-pulse-demeter-secrets \
     -n plexus-pulse
 
 # Apply Kubernetes manifests for Plexus Pulse components
-kubectl apply -f k8s/deployment/plexus-pulse-demeter-app.deployment.yaml -n plexus-pulse
+kubectl apply -f k8s/deployment/plexus-pulse-demeter-app.yaml -n plexus-pulse
 ```

{plexus_python_pulse_demeter-1.1.131 → plexus_python_pulse_demeter-1.1.133}/alembic/env.py

@@ -6,7 +6,7 @@ import sqlalchemy as sa
 from plexus.pulse.common.utils.ormutils import collect_model_tables
 
 from plexus.pulse.demeter.app.models import BaseModel
-from plexus.pulse.demeter.app.models import catalog, inventory, tagging, user, workflow
+from plexus.pulse.demeter.app.models import catalog, inventory, pipeline, tagging, user, workflow  # noqa: F401
 
 database_host = os.getenv("PULSE_DEMETER_DATABASE_HOST", "localhost")
 database_port = os.getenv("PULSE_DEMETER_DATABASE_PORT", "5432")
@@ -14,8 +14,6 @@ database_username = os.getenv("PULSE_DEMETER_DATABASE_USERNAME", "pulse")
 database_password = os.getenv("PULSE_DEMETER_DATABASE_PASSWORD", "pulse")
 database_database = os.getenv("PULSE_DEMETER_DATABASE_DATABASE", "pulse-demeter")
 
-print(inventory.__all__ + tagging.__all__ + catalog.__all__ + user.__all__ + workflow.__all__)
-
 url = sa.URL.create(
     drivername="postgresql+psycopg",
     host=database_host,

plexus_python_pulse_demeter-1.1.133/k8s/argo/plexus-pulse-demeter-pipeline-templates.yaml

@@ -0,0 +1,171 @@
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: plexus-pulse-demeter-pipeline-operations
+spec:
+  templates:
+    - name: initialize
+      inputs:
+        parameters:
+          - name: api-url
+          - name: pipeline-name
+          - name: stage
+          - name: workflow-uid
+          - name: argo-name
+          - name: argo-namespace
+          - name: claim-limit
+      container:
+        image: ruyangshou/plexus-pulse-demeter-tools:latest
+        imagePullPolicy: IfNotPresent
+        command: [ /app/venv/bin/pulse-demeter-tools ]
+        args: [ flow-ops, initialize ]
+        env:
+          - name: API_URL
+            value: "{{inputs.parameters.api-url}}"
+          - name: PIPELINE_NAME
+            value: "{{inputs.parameters.pipeline-name}}"
+          - name: STAGE
+            value: "{{inputs.parameters.stage}}"
+          - name: WORKFLOW_UID
+            value: "{{inputs.parameters.workflow-uid}}"
+          - name: ARGO_NAME
+            value: "{{inputs.parameters.argo-name}}"
+          - name: ARGO_NAMESPACE
+            value: "{{inputs.parameters.argo-namespace}}"
+          - name: CLAIM_LIMIT
+            value: "{{inputs.parameters.claim-limit}}"
+
+    - name: heartbeat
+      daemon: true
+      inputs:
+        parameters:
+          - name: api-url
+          - name: workflow-uid
+      container:
+        image: ruyangshou/plexus-pulse-demeter-tools:latest
+        imagePullPolicy: IfNotPresent
+        command: [ /app/venv/bin/pulse-demeter-tools ]
+        args: [ flow-ops, heartbeat ]
+        env:
+          - name: API_URL
+            value: "{{inputs.parameters.api-url}}"
+          - name: WORKFLOW_UID
+            value: "{{inputs.parameters.workflow-uid}}"
+
+    - name: finalize
+      inputs:
+        parameters:
+          - name: api-url
+          - name: workflow-uid
+          - name: workflow-status
+      container:
+        image: ruyangshou/plexus-pulse-demeter-tools:latest
+        imagePullPolicy: IfNotPresent
+        command: [ /app/venv/bin/pulse-demeter-tools ]
+        args: [ flow-ops, finalize ]
+        env:
+          - name: API_URL
+            value: "{{inputs.parameters.api-url}}"
+          - name: WORKFLOW_UID
+            value: "{{inputs.parameters.workflow-uid}}"
+          - name: WORKFLOW_STATUS
+            value: "{{inputs.parameters.workflow-status}}"
+
+---
+
+apiVersion: argoproj.io/v1alpha1
+kind: WorkflowTemplate
+metadata:
+  name: plexus-pulse-demeter-pipeline-dispatcher
+spec:
+  entrypoint: main
+  onExit: finalize
+  templateDefaults:
+    container:
+      volumeMounts:
+        - name: workdir
+          mountPath: "{{workflow.parameters.workspace-dir}}"
+      env:
+        - name: WORKSPACE_DIR
+          value: "{{workflow.parameters.workspace-dir}}"
+  volumeClaimTemplates:
+    - metadata:
+        name: workdir
+      spec:
+        accessModes: [ ReadWriteMany ]
+        resources:
+          requests:
+            storage: 1Gi
+  arguments:
+    parameters:
+      - name: workspace-dir
+        value: /workspace
+      - name: api-url
+        value: http://plexus-pulse-demeter-app.plexus-pulse.svc.cluster.local
+      - name: pipeline-name
+        value: pipeline_name@1.0.0
+      - name: stage
+        value: stage_name
+      - name: business-template
+        value: business-template
+      - name: claim-limit
+        value: "1000"
+  templates:
+    - name: main
+      steps:
+        - - name: initialize
+            templateRef:
+              name: plexus-pulse-demeter-pipeline-operations
+              template: initialize
+            arguments:
+              parameters:
+                - name: api-url
+                  value: "{{workflow.parameters.api-url}}"
+                - name: pipeline-name
+                  value: "{{workflow.parameters.pipeline-name}}"
+                - name: stage
+                  value: "{{workflow.parameters.stage}}"
+                - name: workflow-uid
+                  value: "{{workflow.uid}}"
+                - name: argo-name
+                  value: "{{workflow.name}}"
+                - name: argo-namespace
+                  value: "{{workflow.namespace}}"
+                - name: claim-limit
+                  value: "{{workflow.parameters.claim-limit}}"
+        - - name: batch
+            template: batch
+    - name: batch
+      steps:
+        - - name: heartbeat
+            templateRef:
+              name: plexus-pulse-demeter-pipeline-operations
+              template: heartbeat
+            arguments:
+              parameters:
+                - name: api-url
+                  value: "{{workflow.parameters.api-url}}"
+                - name: workflow-uid
+                  value: "{{workflow.uid}}"
+        - - name: process
+            templateRef:
+              name: "{{workflow.parameters.business-template}}"
+              template: run
+            arguments:
+              parameters:
+                - name: workflow-uid
+                  value: "{{workflow.uid}}"
+    - name: finalize
+      steps:
+        - - name: complete-stage-run
+            templateRef:
+              name: plexus-pulse-demeter-pipeline-operations
+              template: finalize
+            arguments:
+              parameters:
+                - name: api-url
+                  value: "{{workflow.parameters.api-url}}"
+                - name: workflow-uid
+                  value: "{{workflow.uid}}"
+                - name: workflow-status
+                  value: "{{workflow.status}}"

plexus_python_pulse_demeter-1.1.133/k8s/local/README.md

@@ -0,0 +1,177 @@
+# Run and validate the local example
+
+This guide runs the example pipeline on a local `argo-local` kind cluster with PostgreSQL, the Demeter API, and Argo
+Workflows. Run the commands from the repository root.
+
+## Prerequisites
+
+- A running kind cluster named `argo-local`
+- `kubectl`, `docker`, and `kind`
+- An Argo Workflows installation with its namespace named `argo`
+
+## Start Demeter
+
+Create the application namespace and database credentials:
+
+```sh
+kubectl create namespace plexus-pulse
+kubectl create secret generic plexus-pulse-demeter-db -n plexus-pulse \
+  --from-literal=username=pulse \
+  --from-literal=password='<local password>' \
+  --from-literal=database=pulse_demeter
+```
+
+Build and load the required images into kind:
+
+```sh
+docker build -f docker/plexus-pulse-demeter-app.dockerfile \
+  -t ruyangshou/plexus-pulse-demeter-app:latest .
+kind load docker-image ruyangshou/plexus-pulse-demeter-app:latest --name argo-local
+
+docker build -f docker/plexus-pulse-demeter-tools.dockerfile \
+  -t ruyangshou/plexus-pulse-demeter-tools:latest .
+kind load docker-image ruyangshou/plexus-pulse-demeter-tools:latest --name argo-local
+
+docker build -f k8s/local/example-business-seeder.dockerfile \
+  -t plexus-pulse-demeter-example-seeder:local .
+kind load docker-image plexus-pulse-demeter-example-seeder:local --name argo-local
+
+docker build -f k8s/local/example-business.dockerfile \
+  -t plexus-pulse-demeter-example:local .
+kind load docker-image plexus-pulse-demeter-example:local --name argo-local
+
+docker pull postgres:16-alpine
+kind load docker-image postgres:16-alpine --name argo-local
+```
+
+Start PostgreSQL, initialize the schema, and deploy the API:
+
+```sh
+kubectl apply -f k8s/local/plexus-pulse-demeter-postgres.yaml
+kubectl rollout status statefulset/plexus-pulse-demeter-postgres -n plexus-pulse --timeout=180s
+kubectl wait --for=condition=complete job/plexus-pulse-demeter-postgres-init -n plexus-pulse --timeout=180s
+
+kubectl apply -f k8s/local/plexus-pulse-demeter-app.yaml
+kubectl rollout status deployment/plexus-pulse-demeter-app -n plexus-pulse --timeout=180s
+```
+
+The initialization Job creates tables from the SQLModel definitions for a fresh installation. The repository does not
+provide a migration for existing databases; apply an appropriate migration before reusing an older database.
+
+## Run the example
+
+Install the Argo pipeline templates, apply the example resources, and start the seeder:
+
+```sh
+kubectl apply -n argo -f k8s/argo/plexus-pulse-demeter-pipeline-templates.yaml
+kubectl apply -n argo -f k8s/local/example-business.yaml
+kubectl create -f k8s/local/example-business-seeder.yaml
+```
+
+## Validate the results
+
+Wait for the seeder to finish, then allow the `transform`, `concat`, and `repeat` schedules to process the message. Each
+schedule runs once per minute, so completion can take several minutes. A successful run can have an empty batch; check
+the persisted work items as well as the workflow status. List workflows and inspect a completed workflow's logs:
+
+```sh
+kubectl get workflows -n argo
+kubectl logs -n argo -l workflows.argoproj.io/workflow=<workflow-name> -c main --prefix
+```
+
+Forward the API service in a separate terminal:
+
+```sh
+kubectl port-forward -n plexus-pulse service/plexus-pulse-demeter-app 8000:80
+```
+
+Query the persisted work items from another terminal:
+
+```sh
+curl -fsS 'http://localhost:8000/pulse_demeter/pipeline/work_items/?pipeline_name=example_business%401'
+```
+
+For a fresh database with the default `hello world` input, the response's `work_items` list should contain four work
+items, all with `pipeline_name: "example_business@1"` and `status: "SUCCEEDED"`:
+
+| Producer → Consumer    | `stage_output` | Expected `work_item_result`                                   |
+|------------------------|----------------|---------------------------------------------------------------|
+| `source` → `transform` | `message`      | `{"lowered": "hello world", "reversed": "dlrow olleh"}`       |
+| `transform` → `concat` | `lowered`      | `{"message": "hello worlddlrow olleh"}`                       |
+| `transform` → `concat` | `reversed`     | `{"message": "hello worlddlrow olleh"}`                       |
+| `concat` → `repeat`    | `result`       | `{"message": "hello worlddlrow ollehhello worlddlrow olleh"}` |
+
+Each work item's `outcome` should name its consumer stage, and all four work items should share the source message's
+SHA-256 `dedup_key`. The final value is stored in the `concat` → `repeat` work item's `result`; no further work item
+is created for the terminal stage's output.
+
+The business workspace is under `$WORKSPACE_DIR/$WORKFLOW_UID` on the workflow's shared volume. The heartbeat process
+may exit with code 143 when its workflow finishes.
+
+## How the example pipeline works
+
+### Stages and data flow
+
+The [seeder](example-business-seeder.dockerfile) registers `example_business@1` if it does not exist, verifies the
+topology if it does, and submits a source work item for each input message. The message's SHA-256 digest is used as the
+deduplication key. The [business code](example-business.dockerfile) processes three stages:
+
+1. `transform` consumes a source message and submits two outputs: the lowercase message (`lowered`) and the original
+   message reversed (`reversed`).
+2. `concat` joins those outputs by deduplication key within the claimed batch, concatenates the lowercase and reversed
+   messages, and submits a `result` output. If only one branch is in the batch, it skips that work item so it can be
+   claimed again later. The join does not fetch missing inputs or retain them outside the batch.
+3. `repeat` consumes the concatenated message, doubles it, and records the result on its input work item. It also
+   submits a `result` output, but the API creates downstream work items only for declared consumers. No stage consumes
+   this output.
+
+The [example resources](example-business.yaml) define one CronWorkflow per business stage, each with a claim limit of
+1,000 work items per incoming `(producer_stage, stage_output)` pair. A `concat` batch can therefore contain up to 1,000
+`lowered` work items and 1,000 `reversed` work items, for a total of 2,000. The limit does not guarantee matching
+deduplication keys across inputs; unmatched work items still need to be skipped. `concurrencyPolicy: Forbid` prevents
+overlapping runs of the same CronWorkflow; different stages can run concurrently. Their data dependencies are enforced
+by the availability of work items in PostgreSQL.
+
+### Batch execution and the flow capsule
+
+The [dispatcher](../argo/plexus-pulse-demeter-pipeline-templates.yaml) runs each scheduled batch in three steps:
+
+1. **Initialize.** Unless a matching local capsule already exists, the worker recovers expired stage run attempts for
+   the pipeline and stage, then checks out a batch. Checkout creates a stage run, stage run attempt, and work item
+   attempts and claims up to the configured limit of eligible queued work items per incoming `(producer_stage,
+   stage_output)` pair in one PostgreSQL transaction. Each input is ordered by priority, availability time, and sequence
+   number. The Argo workflow UID determines the stage run's deduplication key, so repeated checkout requests reuse the
+   same claim rather than claim more work items. The worker saves the returned SQLite file as
+   `pulse-demeter-flow-capsule.db` in the shared workspace.
+2. **Process.** A daemon sends a heartbeat every 60 seconds while the business container processes the capsule's fixed
+   batch. Business code records work item results with `FlowCapsule.commit`, `fail`, or `skip`, and records downstream
+   outputs with `submit`. These calls write to the local capsule; they do not update PostgreSQL directly.
+3. **Finalize.** The exit handler uses the Argo workflow status to decide whether to upload the capsule or report a
+   stage run failure, as described below.
+
+### Completion, retries, and recovery
+
+When Argo reports `Succeeded`, the worker freezes a SQLite snapshot and uploads it as the multipart `file` field to the
+stage-run-attempt `commit/` endpoint. The API applies work item results and creates downstream work items in one
+transaction, then marks the stage run and stage run attempt as succeeded. Stage run success does not imply every work
+item succeeded: explicitly failed work items and claimed work items without a result follow the work item failure rules.
+Business code should record a result for every work item.
+
+A skipped attempt remains in history and its work item is queued without consuming retry allowance. Failed work items
+are queued while their retry limit permits it, otherwise they become failed. Work items requeued by a capsule commit
+become eligible again after 60 seconds. Work item attempt numbers continue increasing even when skips do not consume
+retry allowance.
+
+For any Argo status other than `Succeeded`, the worker calls `fail/` without uploading the capsule. Running work item
+attempts become failed, and their work items are immediately eligible for another run if their retry limit permits it.
+The separate `cancel/` API operation instead marks running attempts as cancelled and immediately requeues their work
+items without consuming retry allowance. The exit handler does not call `cancel/` automatically.
+
+Recovery expires running stage run attempts whose last heartbeat is at least 30 minutes old, marks their stage runs
+failed, and immediately requeues eligible work items under the same retry-limit rules as failure. Recovery runs during a
+new initialization, rather than on an independent timer. Heartbeats and commits for expired or recovered attempts
+receive HTTP 409.
+
+The lifecycle endpoints are under `/pulse_demeter/pipeline`: `POST /stage_runs/recover/`, `POST /stage_runs/checkout/`,
+and `POST /stage_runs/{stage_run_uuid}/attempts/{stage_run_attempt_uuid}/` followed by `commit/`, `fail/`, `cancel/`, or
+`heartbeat/`.

plexus_python_pulse_demeter-1.1.133/k8s/local/example-business-seeder.dockerfile

@@ -0,0 +1,121 @@
+FROM ruyangshou/plexus-pulse-demeter-tools:latest
+
+# language=python
+COPY <<'EOF' /app/example_business_seeder.py
+import argparse
+import datetime
+import hashlib
+import itertools
+import json
+import urllib.error
+import urllib.request
+
+from plexus.pulse.demeter.app.models.pipeline import WorkItem, Pipeline
+from plexus.pulse.demeter.app.core.pipeline import validate_topology
+
+
+pipeline = Pipeline(
+    name="example_business@1",
+    topology={
+        "stages": [
+            {
+                "name": "source",
+                "executor": "manual",
+                "outputs": ["message"],
+            },
+            {
+                "name": "transform",
+                "executor": "argo",
+                "props": {"normalization": "lowercase"},
+                "consume": [
+                    {"producer": "source", "output": "message", "max_retrials": 2},
+                ],
+                "outputs": ["lowered", "reversed"],
+            },
+            {
+                "name": "concat",
+                "executor": "argo",
+                "consume": [
+                    {"producer": "transform", "output": "lowered", "max_retrials": 2},
+                    {"producer": "transform", "output": "reversed", "max_retrials": 2, "props": {"branch": "reversed"}},
+                ],
+                "outputs": ["result"],
+            },
+            {
+                "name": "repeat",
+                "executor": "argo",
+                "consume": [
+                    {"producer": "concat", "output": "result", "max_retrials": 2},
+                ],
+                "outputs": ["result"],
+            },
+        ]
+    },
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--api-url", default="http://localhost:8000")
+    parser.add_argument("--count", type=int, default=1, help="Number of distinct inputs per message")
+    parser.add_argument("--batch-size", type=int, default=1000, help="Work items per API request")
+    parser.add_argument("messages", nargs="+", help="Messages to process")
+
+    args = parser.parse_args()
+    if args.count < 1 or args.batch_size < 1:
+        parser.error("--count and --batch-size must be positive")
+
+    base = args.api_url.rstrip("/") + "/pulse_demeter/internal/pipeline"
+
+    def post(path: str, body: dict | list[dict]) -> dict | list[dict]:
+        request = urllib.request.Request(base + path,
+                                         json.dumps(body).encode(),
+                                         {"Content-Type": "application/json"},
+                                         method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                return json.load(response)
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(f"{path}: HTTP {exc.code}: {exc.read().decode()}") from exc
+
+    with urllib.request.urlopen(base + "/pipelines/", timeout=30) as response:
+        existing_pipelines = [Pipeline.model_validate(item) for item in json.load(response)]
+    existing_pipeline = next((item for item in existing_pipelines if item.name == pipeline.name), None)
+    if existing_pipeline is None:
+        post("/pipeline/", pipeline.model_dump(mode="json"))
+    elif validate_topology(existing_pipeline.topology) != validate_topology(pipeline.topology):
+        raise RuntimeError(f"existing pipeline {pipeline.name} has a different topology")
+
+    messages = (
+        message if args.count == 1 else f"{message} {index:05d}"
+        for message in args.messages
+        for index in range(args.count)
+    )
+
+    work_items = []
+    for message in messages:
+        digest = hashlib.sha256(message.encode()).hexdigest()
+        db_work_item = WorkItem(
+            pipeline_name=pipeline.name,
+            producer_stage="source",
+            consumer_stage="transform",
+            stage_output="message",
+            work_item_name="input-" + digest[:16],
+            dedup_key=digest,
+            data={"message": message},
+            available_at=datetime.datetime.now(datetime.UTC),
+        )
+        work_items.append(db_work_item.model_dump(mode="json"))
+
+    submitted = 0
+    for batch in itertools.batched(work_items, args.batch_size):
+        created_work_items = post("/work_items/", list(batch))
+        submitted += len(created_work_items)
+        print(f"Submitted {submitted}/{len(work_items)} work items", flush=True)
+
+
+if __name__ == "__main__":
+    main()
+EOF
+
+ENTRYPOINT ["/app/venv/bin/python", "/app/example_business_seeder.py"]

plexus_python_pulse_demeter-1.1.133/k8s/local/example-business-seeder.yaml

@@ -0,0 +1,32 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Workflow
+metadata:
+  generateName: demeter-example-seeder-
+  namespace: argo
+spec:
+  entrypoint: seed
+  arguments:
+    parameters:
+      - name: api-url
+        value: http://plexus-pulse-demeter-app.plexus-pulse.svc.cluster.local
+      - name: messages
+        value: "hello world"
+      - name: count
+        value: "1"
+  templates:
+    - name: seed
+      inputs:
+        parameters:
+          - name: api-url
+          - name: messages
+          - name: count
+      container:
+        image: plexus-pulse-demeter-example-seeder:local
+        imagePullPolicy: IfNotPresent
+        command: [ "/app/venv/bin/python", "/app/example_business_seeder.py" ]
+        args:
+          - "--api-url"
+          - "{{inputs.parameters.api-url}}"
+          - "--count"
+          - "{{inputs.parameters.count}}"
+          - "{{inputs.parameters.messages}}"

plexus_python_pulse_demeter-1.1.133/k8s/local/example-business.dockerfile

@@ -0,0 +1,87 @@
+FROM ruyangshou/plexus-pulse-demeter-tools:latest
+
+# language=python
+COPY <<'EOF' /app/example_business.py
+from plexus.pulse.demeter.utils import flowutils
+
+
+def main() -> None:
+    capsule = flowutils.capsule()
+
+    stage_run = capsule.stage_run()
+    stage = stage_run.stage
+    if stage not in {"transform", "concat", "repeat"}:
+        raise ValueError(f"unsupported example stage: {stage}")
+
+    work_items = capsule.work_items()
+    if stage == "transform":
+        for work_item in work_items:
+            message = str(work_item.data.get("message", ""))
+            lowered_message, reversed_message = message.lower(), message[::-1]
+
+            capsule.submit(
+                name="lowered",
+                dedup_key=work_item.dedup_key,
+                data={"message": lowered_message},
+            )
+            capsule.submit(
+                name="reversed",
+                dedup_key=work_item.dedup_key,
+                data={"message": reversed_message},
+            )
+            capsule.commit(
+                work_item.work_item_uuid,
+                outcome=stage,
+                result={"lowered": lowered_message, "reversed": reversed_message},
+            )
+
+            print(f"{work_item.work_item_name}: {message!r} -> {lowered_message!r}, {reversed_message!r}", flush=True)
+
+    elif stage == "concat":
+        # Inner join the two branch outputs by the source message's digest.
+        # A digest is shared by all outputs for one source message.
+        lowered_by_key = {work_item.dedup_key: work_item for work_item in work_items if work_item.stage_output == "lowered"}
+        reversed_by_key = {work_item.dedup_key: work_item for work_item in work_items if work_item.stage_output == "reversed"}
+        joined_keys = lowered_by_key.keys() & reversed_by_key.keys()
+
+        for work_item in work_items:
+            if work_item.dedup_key not in joined_keys:
+                capsule.skip(work_item.work_item_uuid)
+
+        for dedup_key in joined_keys:
+            lowered_work_item = lowered_by_key[dedup_key]
+            reversed_work_item = reversed_by_key[dedup_key]
+            lowered_message = lowered_work_item.data.get("message", "")
+            reversed_message = reversed_work_item.data.get("message", "")
+            concatenated_message = lowered_message + reversed_message
+
+            capsule.submit(
+                name="result",
+                dedup_key=dedup_key,
+                data={"message": concatenated_message},
+            )
+            capsule.commit(lowered_work_item.work_item_uuid, outcome=stage, result={"message": concatenated_message})
+            capsule.commit(reversed_work_item.work_item_uuid, outcome=stage, result={"message": concatenated_message})
+
+            print(f"{dedup_key}: {concatenated_message!r}", flush=True)
+
+    else:
+        for work_item in work_items:
+            message = str(work_item.data.get("message", ""))
+            repeated_message = message * 2
+
+            capsule.submit(
+                name="result",
+                dedup_key=work_item.dedup_key,
+                data={"message": repeated_message},
+            )
+            capsule.commit(work_item.work_item_uuid, outcome=stage, result={"message": repeated_message})
+
+            print(f"{work_item.work_item_name}: {message!r} -> {repeated_message!r}", flush=True)
+
+
+if __name__ == "__main__":
+    main()
+EOF
+
+ENTRYPOINT ["/app/venv/bin/python", "/app/example_business.py"]