Tutorial: File-store Roundtrip

Deploy the built-in Quickstart: File Store Roundtrip workflow (quickstart-file-store-roundtrip) to prove the first complete Deployments lifecycle through a durable local hop.

echo -> file-store writer -> file-store reader -> print

Availability

Requires a licensed environment with Deployments enabled and a catalog item present in the selected release/environment. Use a disposable namespace. A local file-store path requires co-location; it is not shared merely because two workers use the same path text.

Prerequisites

• One online, serviceable worker in a run-owned worker group.
• A fresh directory the worker process can create, read, write, and remove.
• Enough disk for the bounded test and explicit retention/cleanup ownership.
• The exact Catalog workflow visible and ready.

Create and plan

1. In Catalog, filter to workflows and select Quickstart: File Store Roundtrip.
2. Choose the exact version and Plan and register.
3. Name the deployment with a unique run prefix.
4. Select the one-worker group.
5. Bind File-store path to the fresh worker-visible directory and use a run-specific filename/GUID prefix.
6. Plan the deployment.

Review the workflow version, generated writer/reader jobs, file-store transport artifacts, one-group placement, replica counts, path, permissions, warnings, and diff. A plan creates no runtime evidence.

Apply and wait

Record workflow, worker-group, deployment, and plan identities. Apply the unchanged fresh plan. Wait until generated jobs are assigned and ready; do not equate Apply acceptance or worker heartbeat with a running roundtrip.

Prove the roundtrip

• Confirm new run-owned files appear beneath the configured path.
• Confirm the reader observes those files and the Print step logs correlated events.
• Compare writer and reader event counts for the same run window.
• Inspect deployment lifecycle events and generated job logs for retries, duplicates, or errors.

The local file and correlated reader output are runtime evidence. This tutorial makes no external-provider acceptance claim.

This run proves storage visibility and correlated readback. It does not prove source acknowledgement after a durable receipt, automatic recovery after an unfinished sink effect, or trusted origin accounting. A reader fingerprint records read progress; it is not a destination completion receipt. Do not interrupt this example and assume that unchanged reader state will retry every unfinished effect.

For those requirements, first confirm the selected release supports an explicit durable-edge contract, then follow Operate a durable edge and the recovery/replay acceptance scenario. Keep workflow decision checkpoints separate from source cursors and consumer completion.

MCP automation

In a read-only MCP session, discover the workflow and preview group/deployment plans. In a separate --max-tool-tier write session, create only the reviewed run-owned group/deployment and apply the unchanged plan. Use the full MCP workflow lifecycle; record the same identities and evidence as the UI path.

Troubleshooting

• Writer errors: verify path creation, permissions, disk headroom, and worker identity.
• Reader stays empty: confirm writer/reader placement and that both see the same actual storage.
• Repeated records: inspect reader cursor/fingerprint state, retries, and whether an old cycle reused the directory.
• Plan changes after review: discard it and generate a fresh plan.
• Apply interruption: inspect proposal/status/events before retrying.

Tear down

Preserve sanitized evidence, preview removal, and delete only the exact run-owned deployment/group. Verify generated jobs and channel artifacts are no longer assigned. Remove only the recorded run directory, then re-list all run-owned surfaces and require zero residue.

Next, build a branching graph in Tutorial: Local Fan-out.