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.

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.