Image and Persistence

Frothy persists the overlay image and rebuilds the base image at boot.

Image Shape

base image and overlay image (image model)

Layer: core
Behavior: The base image contains built-ins, foreign bindings, standard library, and board library. The overlay contains user-created top-level state after boot.
Example:

`gpio.write` is a base-image slot; `myProgram` is usually an overlay slot.

Worked example:

pulse is fn [ led.on: ]
message is "draft"

Here pulse and message live in the overlay. led.on remains a base-image name even when your overlay code calls it.

rebinding and base-name shadowing (image model)

Layer: core
Behavior: Rebinding updates the current value stored in a stable slot. Base names may be shadowed by overlay writes, but dangerous.wipe restores the boot-rebuilt base value.
Example:

blink is fn [ 99 ]
dangerous.wipe

Worked example:

show @blink
blink is fn [ "temporary overlay version" ]
show @blink
dangerous.wipe
show @blink

The first and third show @blink come from the base image. The middle one is your overlay shadowing that same stable slot name.

Persistence Operations

save (interactive base image)

Layer: core
Behavior: Snapshots the overlay image only. The saved walk includes overlay top-level bindings plus persistable objects they own.
Example:

save

Worked example:

record Cursor [ x, y ]
cursor is Cursor: 2, 3
save

What is saved here is the overlay slot cursor plus the persistable record value it owns.

restore (interactive base image)

Layer: core
Behavior: Replaces the live overlay with the persisted overlay. If restore fails, the runtime must remain in a usable base state.
Example:

restore

Worked example:

record Cursor [ x, y ]
cursor is Cursor: 2, 3
save
set cursor->x to 9
restore
cursor->x

After restore, cursor->x is back to 2.

dangerous.wipe (interactive base image)

Layer: core
Behavior: Clears both the live overlay and the stored overlay and returns the running image to base-only state.
Example:

dangerous.wipe

Worked example:

record Session [ count ]
session is Session: 4
save
dangerous.wipe
session

After dangerous.wipe, reading session is an error because both the live and saved overlay copies are gone.

Boot and Recovery

boot (top-level slot)

Layer: core
Behavior: If boot holds Code after restore, the runtime executes it before entering the prompt.
Example:

boot is fn [ led.on: ]

Worked example:

record State [ ready ]
state is State: false

boot is fn [
  set state->ready to true;
  led.on:
]

save

On the next restore path, boot runs before the prompt and can finish that small startup step.

safe boot (recovery surface)

Layer: core
Behavior: Lets you interrupt startup before restore and boot finish, so bad saved state does not trap the device in a broken loop.
Example:

Press Ctrl-C during the safe-boot window, then inspect `boot` or wipe the overlay.

Typical recovery flow:

1. Connect to the device.
2. Press Ctrl-C during the safe-boot window.
3. Run `show @boot` or `info @boot`.
4. Fix the bad slot, or run `dangerous.wipe`.