RBE Runtime Image

The Runtime Image is the immutable linked application snapshot produced by RELC and activated by the running backend. It is the boundary between mutable deployment inputs and the program/configuration RBE actually executes.

This page documents the current Runtime Image contract on main.

What the image contains

The current Rust representation contains, in practical terms:

RuntimeImage {
    imageId
    sourceHash
    serverPolicy
    environment
    routes
    modules
    services
    sources
    symbolTable
    dependencyGraph
    recursiveGroups
    middlewarePlan
    serviceAssignments
    capabilities (typed host requirements)
    routeWasmArtifacts
    routeWasmFallbacks
    executables
}

executables stores immutable parsed Route/Module/Service/Server program snapshots. Route-native WASM artifacts and explicit interpreter-fallback reasons are stored beside those program snapshots rather than being rediscovered from mutable source at request time.

Two cryptographic identities

RBE currently derives two deterministic SHA-256 identities:

sourceHash = SHA-256(canonical REL source set)
imageId    = SHA-256(sourceHash + Route-WASM ABI/compiler versions + canonical settings)

Both values are lowercase 64-character hexadecimal strings.

These are content identities, not digital signatures. They detect/bind exact inputs; they do not prove who produced those inputs. Persistent signed RBI packaging remains separate work.

sourceHash

sourceHash is domain-separated with:

RBE_SOURCE_SET_V1

Before hashing, RELC canonicalizes the source set by sorting entries by SourceId. The hash input binds:

• the number of sources;
• every exact SourceId;
• every exact source byte sequence.

Fields are length-delimited before being fed into SHA-256, so the identity does not rely on ambiguous string concatenation.

A source edit, source addition/removal, or a changed source identity therefore changes sourceHash.

imageId

imageId is domain-separated with:

RBE_RUNTIME_IMAGE_V3

The current image identity binds:

1. the hexadecimal sourceHash;
2. ROUTE_WASM_ABI_VERSION;
3. ROUTE_WASM_COMPILER_VERSION;
4. the effective settings JSON used by RELC.

Settings JSON is hashed deterministically: object keys are sorted, arrays retain order, values retain their JSON type, and each encoded component is length-delimited.

That means equivalent JSON objects with different object-key ordering produce the same image identity, while a meaningful setting/value change produces a different imageId.

Why compiler/ABI versions are included

A source file can remain byte-for-byte identical while the native Route-WASM compiler or ABI changes. Binding those versions into imageId prevents RBE from treating native artifacts produced under a different compiler/ABI contract as the same linked application image.

This matters even while only a strict Route REL subset lowers to native WASM: the image records both native artifacts and interpreter fallback decisions under one identity.

Capability binding

The Container Controller treats Runtime Image identity as authority metadata, not decoration.

Capability manifests are registered against the exact tuple:

Runtime Image ID
+ SourceId
+ Environment
+ Environment generation

The Container capability broker validates the Runtime Image ID as a lowercase 64-character SHA-256 string. A manifest registered for one image cannot silently authorize a different linked image. Capability manifest shape ceilings (grant count, operations per grant, target bytes, operation bytes, and payload bytes) live in the shared ipc-protocol contract; RELC preflights lowered manifests against the same values before registration, while Controller remains the final authority. Authorized host-capability dispatch uses protocol v2 to carry Controller-attested Runtime Image, SourceId, capability ABI, exact Environment, and generation alongside each call; those ownership fields come from admitted execution provenance and are never accepted from guest WASM.

Native WASM artifact registration is also bound to the exact Runtime Image ID + SourceId + capability ABI. Artifact bytes remain deduplicated by SHA-256 in the Container cache, but cache presence alone is never execution authority: Execute must present an artifact hash explicitly registered for that Runtime Image source.

Replacing an Environment generation also invalidates grants tied to the previous generation, so image identity and process-generation identity participate together in the capability boundary.

See runtime.md and source-security.md.

Runtime source authority

Once an image is active, the image—not the mutable REL source files—is the normal runtime authority.

Current behavior includes:

• Route execution from linked Route program snapshots;
• Module resolution from linked Module program snapshots;
• resolved typed Runtime ENV stored in the image;
• resolved ServerPolicy stored in the image;
• deterministic MiddlewarePlan stored in the image;
• symbol/dependency/recursion metadata stored in the image;
• native Route-WASM artifacts/fallbacks pinned to the image;
• Service assignments and typed host-capability requirements pinned to the image. RELC distinguishes local language helpers from host-crossing HTTP, Video Manager, and Service operations and propagates Module requirements to callers. These compiler requirements are not themselves Controller grants; native lowering must still bind exact policy/limits before registration. Public HTTP execution is centralized in core_lib as the public-http Network Broker: interpreter calls and authenticated Container host calls share the same public-address DNS pinning, redirect/proxy denial, controlled-header rules, request/response ceilings, and timeouts. RELC PublicHttp requirements lower to one exact Network/public-http Controller grant with an explicit operation set. Video requirements retain the canonical declaring Module principal (for example learning.catalog) through dependency propagation and lower to exact Video/module:<owner> Controller grants with explicit operation sets. The authenticated Backend host bridge accepts only those module-principal targets, derives VideoLanguage ownership from the authorized target rather than guest payload, and keeps Video Manager internals behind the trusted facade. Service requirements lower to exact Service/service:<name> Controller grants with compiler-derived exported operation sets, and the authenticated Backend adapter rejects raw/unprefixed targets before calling ServiceManager. Route-WASM compiler generation v6 removes the leftover direct Route-to-Service compiler path entirely. A Route may reach Service or Video natively only through one exported Module function pinned by RELC; that Module may contain exactly one returned HTTP, Video, or Service host call with static JSON-resolvable arguments. Video ownership remains the canonical declaring Module principal and Service targets remain exact service:<name> grants. Namespace-wide, dynamic, multi-import, multi-statement, and nested host-call chains remain interpreter fallback.

Service child activation still has its own source/catalog fingerprint contract until Service execution is transported entirely as a persistent image artifact.

Atomic activation

RuntimeImageSlot owns the currently active Arc<RuntimeImage> behind a controlled replacement point.

Readers clone the active immutable snapshot. Candidate image activation follows the model:

Image A active
      |
compile + validate Image B
      |
      +-- failure --> keep A
      |
      `-- success --> atomically replace active snapshot with B

A reader that already holds Image A is not mutated underneath itself when Image B becomes active.

The activation primitive is implemented. A complete automatic file-watcher/reload coordinator is still separate work.

Native Route-WASM artifacts

For routes inside the current native compiler subset, the image stores exact deterministic WASM bytes and artifact identity. Route-WASM ABI v3 remains stable while compiler generation v6 supports direct HTTP host operations plus strict RELC-linked Module wrappers for exact HTTP, Video, and Service calls; Service and Video are never direct Route imports. A linked wrapper is native only when the Route has one imported exported Module function, the Route arguments are static JSON, the Module function contains exactly one return statement, and that return directly calls the Module's one exact host-capability import with JSON values or those bound parameters. Capability kind integers remain defined centrally by ipc-protocol::CapabilityKind, and one generic capability-call emitter handles all supported host kinds. Namespace imports, dynamic host arguments, wider Module bodies, and nested host-call chains remain explicit interpreter fallback. Bodies above the Container execution-input ceiling fail with 413 Payload Too Large rather than escaping to the interpreter. Those bytes are the eligible payload for Container artifact registration. Artifact persistence is durable-or-fail, cached WASM is SHA-256 verified again when reloaded from disk, corrupt hash-path files are quarantined/removed, and the isolated worker independently re-hashes bytes immediately before execution.

Routes outside the subset store an explicit fallback reason instead of being mislabeled as native.

The public HTTP route dispatcher now executes a linked native Route-WASM artifact through the standalone Container runtime when that exact Runtime Image + SourceId has a native artifact. Admission binds the immutable artifact and an exact capability manifest before execution. Controller protocol v8 supports a hash-only rebind for artifacts already SHA-256 verified in its cache, so repeated native calls do not retransmit WASM bytes; a cold/missing cache fails that fast path and requires full artifact registration. Backend never treats its own cache state as authority. The rebind optimization does not replace execution-time durable integrity admission: Execute/runtime dispatch still re-open and SHA-256 verify the content-addressed artifact before worker launch, and the isolated worker verifies it again immediately before Wasmtime execution. Capability-free native routes register an empty manifest; an ABI-v3 directly imported public HTTP operation registers only its compiler-lowered Network/public-http grant and exact operation set. RELC still rejects direct Route-to-Service imports. A compiler-v5 linked Module route instead registers only the exact requirements propagated from that Module, such as Video/module:<owner> or Service/service:<name> with the precise operation set.

Routes outside the native compiler subset continue through the linked REL evaluator using their explicit fallback reason. Once a route is native, Container admission/execution failure is fail-closed and does not silently fall back to the in-process evaluator. Synchronous native execution also has an outer wait budget larger than the public HTTP broker's maximum operation timeout; if that caller deadline is still exceeded, Backend sends authenticated Container cancellation instead of abandoning a live execution. A cancellation/completion race is recovered with one bounded final result read.

Native routes request the logical general Environment profile during manifest admission. Container Controller resolves that profile round-robin across the configured general-N Environments and returns one exact Environment + generation binding. The Execute request then uses that exact Environment; general is never accepted as wildcard execution authority, and the dedicated Payment Environment is never selected by the general profile.

What imageId does not guarantee

The cryptographic identity does not by itself provide:

• publisher authenticity;
• secret storage;
• sandbox isolation;
• authorization for a source that has no capability grant;
• exactly-once execution semantics;
• persistent source-less deployment;
• resistance to a fully compromised host/kernel.

Those concerns belong to separate RBE boundaries: Vault, HostBootstrap, capability manifests, Service/Container process isolation, CONTROL ER, Linux sandbox enforcement, and the future signed RBI format.

Persistent RBI status

The current Runtime Image is an in-memory linked runtime object reconstructed during normal boot from deployment sources/settings.

The planned RBI path will persist a verified source-less image artifact so production packaging can omit raw REL source after a trusted build/deploy step. RBI signing/loading is not complete yet, so deleting REL source after normal boot is not a supported deployment model today.