Record and replay

Windows ARM64 quickstart

Windows ARM64 uses the C backend and needs Clang. After wax new warehouse --example warehouse and cd warehouse, use these commands instead of wax run --record first-run.wxs:

wax run --backend c
waxdbg init
waxdbg --backend c recording create first-run.wxs --frames 8

The first command runs the warehouse. The debugger then runs a fresh instance to create the eight-frame recording. Open first-run.wxs in Inspector or use the recording commands below.

Make a recording

Bind waxdbg to a project, then choose how many frames to run.

cd MyProject
waxdbg init
waxdbg recording create run.wxs --frames 8

recording create compiles the bound project and starts a new instance. This example runs up to eight frames, numbered 0 through 7, then writes run.wxs. The file contains the recorded inputs, frame history, and build and source identity. It does not capture a process that is already running.

After creation, run.wxs is the active recording for the session. Queries, finds, and investigations can omit the path. If Queries/Health.wax declares the query root Game.HealthState, for example:

waxdbg recording queries
waxdbg recording query --range 0:7 --file Queries/Health.wax --name Game.HealthState --columns

To make another file active without starting replay, select it.

waxdbg recording select previous-run.wxs

Pass the path explicitly in scripts or when no session is active. Metadata, frame, and object inspection commands always require it.

waxdbg recording info previous-run.wxs
waxdbg recording frames previous-run.wxs

Read channel outputs

Read named api channel outputs after a recorded frame has completed:

waxdbg recording outputs run.wxs --frame 4

The JSON document includes each group's members, structural types, values, and change tracking. Registers retain their values between writes; event batches contain only the selected frame's events. JSON outputs reflect frame-close publication, including edits through aliases. supportsChanges says whether a member has a change bit; changed is null when it does not.

recording output-schema discovers the bound project's output declarations. recording channels reads recorded host channel inputs. The recording JSON API documents both directions.

Provide channel values

For a complete channel example, create SimulationDemo/wax.json:

{
  "name": "SimulationDemo",
  "version": "0.1.0",
  "dependencies": {},
  "build": {
    "defaultTarget": "app",
    "targets": { "app": { "runtime": "standalone", "bindings": [] } }
  }
}

Create SimulationDemo/Src/App.wax:

host channel Simulation { float timeScale; }
api channel Telemetry { float elapsed; }

api fn Initialize(string[] args) { Telemetry.elapsed = 0.0; }
api fn Update() : bool {
    Telemetry.elapsed += Simulation.timeScale;
    return true;
}
api fn Teardown() : int32 { return 0; }

Save the schedule below as SimulationDemo/inputs.json. Then ask for the project's input schema and create a recording. The debugger supplies the host channel values; a standalone executable would need a host to supply them.

cd SimulationDemo
waxdbg init
waxdbg recording input-schema > input-schema.json
waxdbg recording create run.wxs --frames 120 --inputs inputs.json

Initial values are complete. Later entries contain only the values that change, and each entry names its frame. Array position has no timing meaning.

{
  "channelInitialValues": {
    "Simulation": { "timeScale": 1.0 }
  },
  "frameInputs": [
    {
      "frameId": 12,
      "values": {
        "Simulation": { "timeScale": 0.5 }
      }
    }
  ]
}

The generated schema covers required members, optional channels, events, secrets, atomic text operations, and every structural value accepted by the project.

Read the published output around the change and at the end:

waxdbg recording outputs run.wxs --frame 11
waxdbg recording outputs run.wxs --frame 12
waxdbg recording outputs run.wxs --frame 119

Telemetry.elapsed is respectively 12, 12.5, and 66: frames 0 through 11 advance by 1, then frames 12 through 119 advance by 0.5.

Recording or snapshot

A recording keeps the input timeline and inspectable frame history. Saved checkpoints make seeking possible.

A snapshot holds one Wax runtime state at a frame boundary. It does not contain host memory or host interface state, and native handles are not valid after restore. Snapshot creation and restoration belong in the embedding API, not in recording create.

Inspect the run

Open a recording in the Inspector after the original process has exited.

waxdbg gui run.wxs

The command line reads the same file.

waxdbg recording info run.wxs
waxdbg recording diff run.wxs --range 0:7
waxdbg recording timeline run.wxs --object @3

Use Queries and investigations for typed results and scans across many frames. Integrations can read the recording JSON contract.

Run changed source

continue-edited compiles the project as it exists now and feeds it inputs from an earlier recording.

Use the SimulationDemo project and its 120-frame run.wxs from above. In SimulationDemo/Src/App.wax, replace Update with:

api fn Update() : bool {
    Telemetry.elapsed += 2.0 * Simulation.timeScale;
    return true;
}

From the SimulationDemo directory, replay the earlier inputs through frame 60:

waxdbg recording continue-edited run.wxs --frame 60

The wxdbg.recording-continue-edited.v1 result reports ok: true, category: "success", and frame: 60, with the edited source fingerprint. The original recording is unchanged. Select a frame within the recording's seekableStartFrame and seekableLastFrame, reported by recording info; the last recorded frame can lie beyond this replay window.

The new build starts with a fresh heap at frame zero. The recorded build does not run, and no recorded objects are copied into the new heap.

Wax stops if the project does not compile, a recorded API no longer has the same identity, a channel changed shape, required inputs are missing, or a visible host function result cannot be replayed safely. Code changes that leave the recorded boundary intact are allowed. A new channel starts with its normal initial value.