Journeys
A journey describes one situation you want your system to play out: where a request starts, what data it carries, and how far the run may go. The diagram is the map; the journey is the trip.
What a journey is
A journey supplies the starting conditions for a run without changing your diagram. It answers three questions: where does the run start (which component and output port), what data is involved (the request payload and any records already sitting in databases, caches, queues, or dependencies), and when should the run stop (limits on events and virtual time).
The compiler turns the compatible graph and journey into a normalized execution plan. The run stores graph, journey, plan, engine, executor, and serializer versions with a reproducibility key. The same saved graph, journey content, fixtures, limits, and pinned versions therefore produce the same deterministic event record; a new run still starts from fresh fixture state.
Create a journey
- In the editor, open the Journey tab in the workbench dock at the bottom of the screen.
- Press New journey, or Make a copy to start from a copy of the current one. The Journey dropdown switches between drafts. A clone keeps a source link and can be placed in the same journey group.
- Set the journey name, start component, starting action and input data. Changes autosave as you type. Open Starting component state or Additional settings when needed.
The journey form at a glance
Journey name and start — choose the Start component and Starting action (an output port) where the run begins. A source actor is the usual starting point, but an eligible boundary output can also be a start.
Input data — the JSON sent when the journey begins, up to 256 KiB. Expand Starting component state to find a component by name. Its ID is linked automatically. Use the Builder to enter property names, types and values, including nested objects and ordered arrays. Switch to JSON to paste or edit raw data. Only components that accept starting state appear in the list; configured data for removed components stays visible for repair. Use the component’s example to start with the expected structure, then add your records. The editor manages component IDs and preserves unfinished edits while switching components. Invalid JSON blocks saving and running until repaired. Use All JSON for bulk edits andBy component to return after fixing any invalid bulk JSON.
Additional settings — description, Journey group (optional), Event limit (1–10,000 recorded events), and Simulated time limit (ms). One action can produce multiple events. The simulated clock is different from real waiting time. Existing limits are preserved and summarized when the section is closed.
The stored reference number remains part of the journey data but is no longer an editable control. It does not change the route or timing in the current engine.
Ready to run appears beside the Run button when the current journey and diagram pass configuration checks. Issues appear in context when something needs repair. This status does not mean a simulation has run or its promises have passed.
The form autosaves after a short pause, and running a journey waits for its edits to save. A failed save offers Retry save. If another edit wins the save, choose Keep mine or Use latest. Journey options contains Delete journey, which requires confirmation.
Inputs and fixtures
The input payload is the JSON carried by the first token. Fixtures are the state that exists before that token is emitted. The engine copies fixtures into run-local state, so a cache write, queue transition, workflow step, or database mutation cannot overwrite the journey's starting JSON or another run.
A concrete cache-aside setup
In a diagram with these illustrative component IDs, start at client, output requestOut, with input data { "productId": "sku-42" }. Configure the cache key path and database get key path as /productId, and the database collection as products. The starting state below gives the cache a miss and the database a matching record. Replace the IDs with your own; the diagram still needs handlers for the lookup, database call, cache write-back, and response. A safe example can use seed 0, max events 1000, and max virtual time 3600000 milliseconds.
{
"cache": {},
"database": {
"products": {
"sku-42": {
"name": "Desk lamp"
}
}
}
}Fixture contracts follow the configured component. Cache entries use the configured cache key. A database fixture is a collection keyed by record key. An object-store fixture is a bucket keyed by the scalar value at its configured key path, and a stored object needs its configured status to count as a hit. Queue fixtures contain messages keyed by deterministic message ID. A fixture target that is missing or has the wrong component type makes the journey incompatible.
The form requires starting component state to be a JSON object keyed by component ID. Payload and fixture content are checked against the 256 KiB payload and 10 MiB aggregate fixture limits. Keep values small and explicit so the resulting event and state diffs remain useful.
Keep the journey compatible
The run check compares the current form values with the current graph. It verifies the schema, expression, and serializer versions; the start node and eligible start port; fixture targets and component types; and content limits. A database fixture collection that no longer matches the Database settings is a review warning rather than an invisible rewrite.
The panel uses Ready, Check needed, Fix needed, and Checking. A graph change can remove the selected start node or port, change a fixture target, or require review. The command-bar run menu lists only saved, compatible journeys.
If a journey is missing from the run menu, open the Journey tab, repair the highlighted start, fixture, or version problem, and wait for the draft save and compatibility check to finish.
How a run executes
A compatible journey is compiled before it runs. The plan contains the entry, normalized nodes and edges, interactions, limits, estimated counts, and executor versions. The deterministic scheduler then orders actions by virtual time, priority, and scheduling order. Node durations, boundary latency, waits, and retry backoff advance the simulated clock.
Port handlers run their ordered actions. The supported action shapes include call, await, map, for_each, emit, respond, fail, and assign. Conditions are evaluated against payload, input, variables, fixtures, or arrival context. Calls can wait for a response; a for-each dispatches bounded child work; a catch can route a handled failure with rejected or degraded outcome.
Branches carry token lineage. A join records each matching arrival, becomes satisfied when its barrier is met, or records a timeout when a required branch does not arrive in time. A timeout can schedule a retry when the interaction policy allows it. Queue failures can be requeued or dead-lettered, and workflow failures can run compensation. The full order is visible in the Events reference.
Run it
The fastest path is the numbered Run 01 control in the editor command bar. Wider viewports also preview its journey name; the label contracts as space becomes tighter. Its arrow always lists every compatible journey with the full name as 01, 02, and so on. Choose a journey to make it the active run choice, then press the main numbered button to save pending journey edits and start it immediately. The run dock opens automatically.
You can run directly from the Journey tab with Run this journey, or switch to the Run tab and press Run journey. The panel shows Preparing, Running, Stopping, Finished, Stopped, or Failed. A stopped run can be guarded or cancelled; its artifact summary explains which terminal status was recorded. Use Try again to start a new run from the same saved fixtures.
Timeline and Transcript keep the completed journey name, run number, reference number, and draft provenance visible. Choosing a different next journey does not relabel the immutable run being inspected.
A finished artifact reports event count, virtual duration, optional terminal code, responsible component, and run hash. The summary also reports warning and error counts, stages, tokens, outcome, and remediation when available. These runs demonstrate configured behavior and ordering; times and results are examples, not production predictions.
Editor runs execute in your browser against modeled data. They do not call production services or change your working diagram or journey. MCP runs execute in a server worker and return transient evidence; they do not save an approved run.
Understand reads, writes, and run state
Every run starts from a fresh copy of the journey fixtures. A cache write, queue transition, workflow step, or database mutation changes only that run's simulated state. Run the same saved journey again and it starts from the same fixtures, content, limits, and pinned versions.
A current Database component can get or query records, or insert, update, upsert, and delete them. For a write, Record path selects the record inside the incoming JSON and Key path selects that record's stable key. For example, a payload shaped like {"job":{"jobId":"job-1001","status":"open"}} uses /job as its record path and /jobId as its key path.
In the run timeline, a successful write produces a database mutation event followed by a state patch. Inspect the state before and after that patch to see the exact record that changed. Insert fails when the key already exists; update and delete fail when it does not; upsert handles either case.
Record and key paths use JSON Pointer syntax: an empty path selects the whole value, while a nested value starts with /. Editor diagnostics report an invalid path. The journey compatibility panel reports a fixture collection name that does not match the Database settings.
Replay it, step by step
After a run, switch to Simulate mode to replay the stored artifact without changing anything. This is playback of the recorded event log, not a second execution. The controls play and pause, step one event or one stage in either direction, scrub to a position, restart, and change speed. Watch the canvas while it plays; the active connection and current step follow the selected event.
The Timeline and Transcript show the same authoritative events. Inspect can resolve payload before and after references and reconstruct state before and after an event from the run's automatic state checkpoints. A new Try again run creates a fresh artifact rather than mutating the previous one. A run hash identifies content, not a unique attempt: repeated identical runs can have the same hash.
Breakpoints pause review at a node, stage, event kind, error, or simple attempt or virtual-time condition. They change playback only, not the run result. See Runs & events for the event kinds and timeline reading guide.
Compare journey variants
Give related journeys the same Journey group — say, “Checkout” with a happy-path variant and a payment-fails variant. The Journey matrix panel lets you select two to eight compatible variants from that group, then press Compare selected variations. It runs at most two at once and shows each one's status, path, and outcome in a table. The combined configured event limits cannot exceed 40,000.
On the canvas, the Journey route focus toolbar highlights routes: All topology shows the whole diagram, Potential route highlights the reachable topology compiled for the selected journey, and Actual route highlights the recorded traversal in the loaded run artifact. Potential reachability is not proof that every branch executed. Selecting another journey does not change the recorded route of the run you are inspecting.
Add journeys to a checkpoint
A draft is where you keep working; a diagram checkpoint is a saved review point that does not change underneath you. Select Checkpoint in the editor command bar, add an optional message, choose the journey drafts to include, and create the checkpoint. The checkpoint stores a graph revision and immutable snapshots of the selected journey content and hashes.
You can deselect all journeys to make a diagram-only checkpoint, even when journeys exist. Ready journeys are selected by default; Check needed journeys can be included after reviewing their warnings. Fix needed journeys must be repaired first. Creating a checkpoint does not replace your draft or delete older checkpoints. Creation stops at five checkpoints; existing legacy versions remain readable.
This is different from a state timeline checkpoint. The latter is created automatically inside a run artifact so playback can reconstruct component state efficiently. It is not a saved journey version and it is not the editor's Checkpoint command.
See Drafts and checkpoints for the complete explanation and step-by-step instructions.
Journey names in saved data and MCP
The product calls these records journeys. Existing API names still use scenario: a journey draft contains a scenario.v1 document, expression.v1 expressions, and canonical-json.v1 serialization. MCP tools such as get_scenario_draft and run_scenario_draft operate on journeys, not a separate feature. Keep those exact identifiers in integrations. See running journeys through MCP for permissions and version-token guidance.