Chapter 33: Bytecode, Images, And Source Emission

Part V: Packages, Registries, Macros, Tooling, and Release

Why this chapter matters

Bytecode and images are runtime artifacts. Understanding them helps you separate source, compiled code, saved VM state, and emitted source views.

What you will build

You will build an image lab for compiled and persistent runtime artifacts. The example script creates ordinary language state, compiles to bytecode, runs that bytecode, saves a VM image after running the source file, inspects the image, and emits readable source-like text from the bytecode.

Concepts in plain English

Bytecode is compiled code. An image is saved VM state. Source emission is a readable representation produced from bytecode.

The chapter uses these concepts:

• Bytecode build and run commands.
• REPL images, save/load, and binding inspection.
• Source emission as readable output rather than exact reconstruction.
• Image safety boundaries for retained resources and sensitive values.

Vocabulary and commands

Primary coverage: rco build, .rcob bytecode files, rco run-bytecode, rco image save, rco image inspect, rco image inspect --json, and rco emit-source.

Guided example

Open examples/learn/33-bytecode-images-and-source-emission/image_lab.rco:

code"Image lab" println

"ada" user_name var
$user_name uppercase user_code var

scores array
$scores 10 push drop
$scores 20 push drop
$scores 12 push drop

( values -> Number ) lab_sum function
  values var
  0 total var
  [
    value var
    $total $value + total set
  ] $values each drop
  $total
end

$scores lab_sum score_total var

"user:" print
$user_code println

"score total:" print
$score_total println

The lab runner builds, runs, saves, inspects, and emits in order:

codepowershell -ExecutionPolicy Bypass -File examples/learn/33-bytecode-images-and-source-emission/run-lab.ps1

The runner changes into the example directory before calling the CLI, so generated files stay local to the lab:

coderco build image_lab.rco
rco run-bytecode build/app.rcob
rco image save session.rci --source image_lab.rco
rco image inspect session.rci
rco emit-source build/app.rcob

The first command writes build/app.rcob:

codebuilt build/app.rcob

Running the bytecode should match the source program:

codeImage lab
user:ADA
score total:42
[]

image save --source runs the source file first, then stores safe VM state:

codesaved image session.rci (4 bindings, 1 functions, 0 classes)

image inspect shows the preserved names:

codeformat ricochet-vm-image
format_version 1
ricochet_version 0.1.19-rc.4
stack 0
variables score_total, scores, user_code, user_name
functions lab_sum
classes

Use JSON for tooling:

coderco image inspect session.rci --json

emit-source is a readable view over compiled bytecode:

coderco emit-source build/app.rcob

The output starts with a provenance comment:

code(( emitted from bytecode chunk "image_lab.rco" ))
"Image lab"
println

Do not expect emitted source to be the original file. It may show lower-level operations such as "user_name" get because it is explaining bytecode, not preserving author formatting.

How to read the example

Read artifact examples by separating source from output. Source files are what you edit. Bytecode, images, packages, and update metadata are generated artifacts with their own verification steps.

Try it

Run only the bytecode steps:

codePush-Location examples/learn/33-bytecode-images-and-source-emission
rco build image_lab.rco
rco run-bytecode build/app.rcob
Pop-Location

Inspect the image as JSON:

codePush-Location examples/learn/33-bytecode-images-and-source-emission
rco image inspect session.rci --json
Pop-Location

Experiment in the REPL with an image path:

coderco repl --image scratch-session.rci

Inside the REPL, use :bindings, :save, :save other.rci, and :load other.rci to manage checkpoints.

Check your understanding

• What new value shape, command, or host boundary did this chapter introduce?
• Which line is most important to trace with a stack diagram?
• Where would you add a binding to make the example easier to read?

Common mistakes

• Treating emitted source as the original file.
• Assuming every retained runtime resource belongs in a saved image.
• Building from a directory that contains the example path and wondering why build/app.rcob appears there. Run build commands from the project or example directory you want to own the artifact.
• Committing regenerated bytecode or image files without checking whether they are meant to be source artifacts. This lab ignores build/ and session.rci because they are reproducible outputs.
• Expecting images to save process-local handles such as tasks, streams, sockets, processes, PTYs, active approvals, or literal secret references.

Safety notes

Images are VM-state snapshots, not operating-system process snapshots. They preserve ordinary language state such as nil, booleans, numbers, strings, arrays, lists, maps, sets, classes, instances, blocks, functions, and results. They reject process-local or sensitive state rather than silently dropping it.

Review emitted source and image inspection output before sharing. They can include binding names and values that were safe to serialize but still private to your application.

Production guidance

Production artifact workflows should preserve version metadata, source inputs, build commands, self-check commands, and expected runtime capabilities. Use run-bytecode --trace-file when you need debugger events from a compiled artifact, and use emit-source for inspection or recovery workflows, not as a source-code formatter.

Reference links

• docs/reference/guides/images-source.html
• docs/wiki/language-runtime.html
• docs/reference/guides/features.html
• docs/debugger-integrations.html

What you know now

You know how Ricochet exposes compiled artifacts and persistent runtime state: build bytecode, run bytecode, save and inspect VM images, use REPL image checkpoints, and emit readable source-like bytecode views.

Next step

Continue to Chapter 34: Packaging, Release, And Updates.