@elizaos/app-core 2.0.0-beta.3 → 2.0.11-beta.6

package/scripts/bun-riscv64/bun-version.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "Single source of truth for the Bun riscv64-linux-musl cross-build. Read by build.sh + Dockerfile build args + any downstream artifact-hosting publish step. Bump these together with the matching webkit-patches/ and bun-patches/ series.",
+  "bun": {
+    "tag": "bun-v1.3.14",
+    "channel": "canary",
+    "rationale": "bun-v1.3.14 is the LAST Zig release of Bun. It is the last-validated riscv64 build (bun-patches/ series) and the safe fallback. Bun's core was rewritten Zig->Rust (oven-sh/bun PR #30412, merged 2026-05-14); see rust_core_port below for the in-progress migration of the riscv64 cross-build onto the Rust core. Keep this pinned to match stage-android-agent.mjs:BUN_VERSION until the Rust-core riscv64 cross-build is green."
+  },
+  "rust_core_port": {
+    "status": "GREEN (2026-05-31). `./run-build.sh --rust-core` builds end-to-end with patch series 0001-0010: WebKit JSC C_LOOP, full libbun_rust.a (build-std + ~200 crates), all C++ bindings, final link, package. QEMU smoke PASSES: the artifact is a UCB RISC-V double-float-ABI musl ELF; `bun --version` -> 1.4.0 (Rust core, not the Zig 1.3.14 fallback), `bun -e` and `bun <script.js>` both run and report process.arch === 'riscv64'. Artifact dist/bun-linux-riscv64-musl.zip sha256 010ea2a3c7b0b197d0b226ee408d78c359590561e9864314bb6af0cc409694cb (~19MB, C_LOOP no-JIT). This Rust-core build is now the validated riscv64 bun; the Zig v1.3.14 build remains the documented fallback.",
+    "target_commit": "9d000561c937b8e00569519ba1c7973e4b967fb5",
+    "target_ref": "main (Rust-core; language=Rust, no build.zig)",
+    "rust_channel": "nightly-2026-05-06",
+    "rust_channel_source": "rust-toolchain.toml on oven-sh/bun@main (verified 2026-05-29)",
+    "rust_target": "riscv64gc-unknown-linux-musl",
+    "webkit_commit": "963f8758c29e965471c191668d5776a1a1b014b6",
+    "webkit_commit_source": "scripts/build/deps/webkit.ts:WEBKIT_VERSION on oven-sh/bun@9d000561 (verified 2026-05-30) — distinct from the Zig-era 5488984d; webkit-patches/ must be refreshed against it.",
+    "patch_series": [
+      "rust-core/0001-riscv64-rust-core-port.patch (31 files: build-system Arch/target + C++ C_LOOP guards; applies clean + tsc-clean)",
+      "rust-core/0002-second-wave-riscv64-source-gaps.patch (4 files: env.rs Architecture::Riscv64/process.arch, Global.rs arch_name, CPUFeatures.rs riscv64 Flags, hw_timer.rs rdtime CSR — fixes the compile_error! hard-stops; rdtime asm validated via rustc)",
+      "rust-core/0003-third-wave-riscv64-crash-handler-gaps.patch (1 file, src/crash_handler/lib.rs: Platform::CURRENT riscv64 arm b'r' — the HARD compile error, a cfg-matrix const with no catch-all; fault_context_from_ucontext riscv64 ucontext arm reading __gregs[0]/[8] (pc/fp) + not(any) exclusion; ARCH_DISPLAY_STRING -> riscv64; applies clean on top of 0001+0002)",
+      "rust-core/0004-rust-target-cpu-riscv64.patch (1 file, scripts/build/rust.ts: -Ctarget-cpu=generic-rv64 for riscv64 — it was falling through to the aarch64 'cortex-a72' default, aborting the cargo build of core/compiler_builtins with 'rustc-LLVM ERROR: RV64 target requires an RV64 CPU')",
+      "rust-core/0005-fifth-wave-riscv64-source-gaps.patch (2 files: install_types/resolver_hooks.rs npm cpu-field Architecture bitflag — RISCV64 bit + ALL_VALUE + name parser + CURRENT/CURRENT_NAME arms (hard E0308); windows_sys/externs.rs teb()/peb() not(any(x86_64,aarch64)) unreachable!() arm so the workspace crate typechecks on riscv64)",
+      "rust-core/0006-cpp-wasm-and-inspector-guards-riscv64.patch (2 files: runtime/bake/BakeGlobalObject.cpp #if ENABLE(WEBASSEMBLY) guard on compile/instantiateStreaming method-table slots — the Zig bun-patches/0009 hunk didn't rebase because bake moved src/bake/->src/runtime/bake/; jsc/bindings/BunDebugger.cpp whole-TU #if __riscv stub of the 9 extern-C debugger entry points since JSGlobalObjectDebuggable/inspectorController are REMOTE_INSPECTOR-only)",
+      "rust-core/0007-bun-alloc-max-align-t-riscv64.patch (1 file, src/bun_alloc/lib.rs: hardcode MAX_ALIGN_T=16 for riscv64 — the libc crate has no max_align_t for riscv64gc-unknown-linux-musl (E0425); riscv64 LP64D long double is binary128/16-aligned, same as the existing freebsd-aarch64 hardcode)",
+      "rust-core/0008-workspace-lints-warn-not-deny-riscv64.patch (1 file, root Cargo.toml [workspace.lints.rust]: demote the `warnings` group AND the dead_code/unused_*/unreachable_* family from deny->warn — arch-gated code leaves items unused on riscv64 (e.g. bun_core::debug::PC_OFFSET, used only by return_address()'s x86_64/aarch64 arm). The `warnings` group at deny re-escalated the per-lint warn, so the group itself must be demoted. riscv64 build tree only)",
+      "rust-core/0009-zigglobalobject-wasm-streaming-guards-riscv64.patch (2 files, jsc/bindings/ZigGlobalObject.{cpp,h}: ENABLE(WEBASSEMBLY) guards on the JSWasmStreamingCompiler.h include, both GlobalObjectMethodTable compile/instantiateStreaming slots, the m_wasmStreamingConsumeStreamFunction initializer, the extern-C streaming block (JSC::Wasm::StreamingCompiler/CompilerMode), and the two .h decls — the Zig bun-patches/0009 ZigGlobalObject hunks didn't rebase into 0001)",
+      "rust-core/0010-tcc-externs-stub-on-riscv64.patch (2 files, tcc_sys/tcc.rs + runtime/ffi/mod.rs: add riscv64 to the not(any(android,freebsd,win-aarch64)) gate so the tcc_* externs are unreachable!() STUBS on riscv64 — config.ts disables tinycc for riscv64 so libtcc isn't linked; without this the externs were referenced -> undefined symbols at the final link)",
+      "rust-core/0011-clippy-ptr-cast-lints-warn-riscv64.patch (1 file, root Cargo.toml [workspace.lints.clippy]: demote ptr_cast_constness/ptr_as_ptr/ref_as_ptr/borrow_as_ptr + large_types_passed_by_value deny->warn — the only two deny-level clippy lints that fire on riscv64, both from c_char-unsigned / target-layout ABI divergence on upstream code that upstream's x86_64-only clippy CI never sees. `cargo clippy --workspace --target riscv64gc-unknown-linux-musl` is then ERROR-FREE (exit 0); soundness clippy lints stay at deny)"
+    ],
+    "remaining": "GREEN end-to-end (see status). Clippy --workspace for riscv64 is error-free with 0001-0011. Optional follow-ups: realize the WebKit LLInt/Baseline JIT cherry-pick recipes (currently C_LOOP-only); ICU icudt74l.dat packaging if NFKC/NFKD normalization is exercised.",
+    "rationale": "Upstream scoped the Rust rewrite to linux-x64-glibc; this port teaches bun's Rust build system (config.ts/rust.ts) the riscv64gc-unknown-linux-musl target, rebases the riscv64 C_LOOP/source guards onto main (0001), and fixes the compile-stop source gaps (0002). Activate with `./run-build.sh --rust-core` (sets BUN_RISCV64_RUST_CORE=1 → build.sh uses target_commit + rust_channel + webkit_commit and mounts rust-core/ as the patch series)."
+  },
+  "webkit": {
+    "fork": "oven-sh/WebKit",
+    "fork_commit": "5488984d20e0dbfe4be2c3ba8fb18eb81a5e0e8b",
+    "fork_commit_source": "scripts/build/deps/webkit.ts:WEBKIT_VERSION on oven-sh/bun@bun-v1.3.14 (verified 2026-05-28)",
+    "rationale": "Bun's WebKit fork has zero riscv64 patches. We checkout this commit, apply the checked WebKit-side patch files, and build the production artifact with the portable C_LOOP interpreter until the LLInt/Baseline cherry-pick recipes are realized as actual patch files.",
+    "jit_tier": "c_loop",
+    "jit_rationale": "The production riscv64-linux-musl artifact is C_LOOP-only: build.sh defaults to ENABLE_C_LOOP=ON, ENABLE_JIT=OFF, ENABLE_DFG_JIT=OFF, and ENABLE_FTL_JIT=OFF. Upstream WebKit has LLInt + Baseline support for riscv64, but the local cherry-pick chain is still represented by recipe files rather than checked patch files. Operators may set BUN_RISCV64_FORCE_CLOOP=0 to test the experimental Baseline path after realizing those recipes; that is not the publishable artifact contract.",
+    "cherry_pick_targets": {
+      "llint_landing_sha": "d9b48eb602eb0269030f018afddd16c560d0b501",
+      "llint_landing_date": "2021-08-30",
+      "llint_bug": "https://bugs.webkit.org/show_bug.cgi?id=229035",
+      "baseline_enable_sha": "2abfe1cc0ddc0aa1cc65e9141e0548294a921713",
+      "baseline_enable_date": "2022-04-25",
+      "baseline_bug": "https://bugs.webkit.org/show_bug.cgi?id=239708",
+      "first_pick": "d9b48eb602eb0269030f018afddd16c560d0b501",
+      "last_pick": "2abfe1cc0ddc0aa1cc65e9141e0548294a921713",
+      "pick_count_approx": 15,
+      "rationale": "These two SHAs bracket the cherry-pick chain that needs to land on top of webkit.fork_commit. The full ordered list is in webkit-patches/0001-cherry-pick-llint-riscv64.recipe. An operator with two WebKit clones produces the patch series mechanically from this range."
+    }
+  },
+  "toolchain": {
+    "llvm": {
+      "version": "21.1.8",
+      "rationale": "Pinned by Bun upstream (LLVM_VERSION in scripts/build/config.ts on main). Mismatches between the LLVM used to build WebKit/Bun and the one packed into the artifact cause memory-allocation failures at runtime."
+    },
+    "zig": {
+      "version": "0.14.1",
+      "sha256_x86_64_linux": "24aeeec8af16c381934a6cd7d95c807a8cb2cf7df9fa40d359aa884195c4716c",
+      "rationale": "Bun's codegen uses Zig 0.14+ (target syntax: <arch>-<os>-<abi>). 0.14.1 accepts `riscv64-linux-musl`. The codegen runs on the build host (x86_64) and emits source files that are then compiled by clang for the target, so the Zig binary itself does not have to be a riscv64 build."
+    },
+    "rust": {
+      "channel": "nightly-2025-12-10",
+      "channel_source": "rust-toolchain.toml on oven-sh/bun@bun-v1.3.14 (verified 2026-05-28)",
+      "target": "riscv64gc-unknown-linux-musl",
+      "tier": 2,
+      "rationale": "Bun pins this exact nightly via rust-toolchain.toml. riscv64gc-unknown-linux-musl is a Tier-2 target with prebuilt std, so we get it via `rustup target add` rather than -Zbuild-std."
+    },
+    "musl": {
+      "version": "1.2.5",
+      "alpine_branch": "v3.21",
+      "alpine_branch_source": "stage-android-agent.mjs:ALPINE_BRANCH",
+      "rationale": "Alpine v3.21 ships musl 1.2.5 across all arches including riscv64. Matching musl versions between the Bun binary and the Android runtime sysroot is mandatory \u2014 the ld-musl-riscv64.so.1 we pack with the APK comes from this same Alpine branch."
+    }
+  },
+  "dependencies": {
+    "_rationale": "Everything outside WebKit + TinyCC builds on riscv64gc-linux-musl with no patches. TinyCC has no riscv64 backend in oven-sh/tinycc, so we disable bun:ffi JIT-compile for this artifact.",
+    "boringssl": {
+      "status": "supported",
+      "notes": "Uses C fallbacks for AES on riscv64."
+    },
+    "mimalloc": {
+      "status": "supported"
+    },
+    "c-ares": {
+      "status": "supported"
+    },
+    "zstd": {
+      "status": "supported"
+    },
+    "libdeflate": {
+      "status": "supported"
+    },
+    "lol-html": {
+      "status": "supported",
+      "notes": "Rust crate, std is Tier-2."
+    },
+    "zlib": {
+      "status": "supported"
+    },
+    "libarchive": {
+      "status": "supported"
+    },
+    "ls-hpack": {
+      "status": "supported"
+    },
+    "tinycc": {
+      "status": "disabled",
+      "rationale": "oven-sh/tinycc fork has no riscv64-gen.c / riscv64-asm.c / riscv64-link.c \u2014 the upstream `mob` branch lands the riscv64 backend ad-hoc but it has never been merged into oven-sh/tinycc. Disabling means bun:ffi JIT-compile is unavailable on riscv64; static FFI bindings still work. Acceptable for the Android agent runtime."
+    }
+  },
+  "artifact": {
+    "filename": "bun-linux-riscv64-musl.zip",
+    "internal_layout": "bun-linux-riscv64-musl/bun",
+    "matches_oven_release_naming": true,
+    "matches_rationale": "stage-android-agent.mjs:ensureBunBinary unzips and expects the inner directory to be `bun-linux-${bunArch}-musl`. Keeping the layout identical to upstream's other release zips lets the existing fetch path work unmodified once ELIZA_BUN_RISCV64_URL is set."
+  },
+  "patch_series": {
+    "_rationale": "SHA256 of every patch + recipe under bun-patches/ and webkit-patches/. validate.sh checks these match before invoking the build. Bump alongside the patch content.",
+    "bun_patches": {
+      "0001-config-add-riscv64-arch.patch": "7ffff10be9048bc1c0ffed987a407cda5d5470550e21de39d36913c6e9a1918d",
+      "0002-flags-add-riscv64-march-mabi.patch": "4140dd014c650cecdebcd495f3c7193ffcd6be4afe9d28b51394b658e14c0896",
+      "0003-zig-add-riscv64-target-triple-and-cpu.patch": "d323f8ce19178748c37167fadba257f0bd1bb619cb1adb804994824c72812646",
+      "0004-webkit-force-local-mode-on-riscv64.patch": "1e6f5de122a7ba59d6b99d9f14d9f2390fc5c11b1c3ad61b8cc8a7b6b75d838a",
+      "0005-tinycc-disable-on-riscv64.patch": "ee3e9b0c64a5ccdb78397309ce2115381c353a3dfce313aba88dd951264dc7d3",
+      "0006-build-add-riscv64-cli-validation.patch": "d621bff9ae125af7674bb4ee44dad62848c1ab6e333e61d4b1f6311eb139764c",
+      "0007-deps-per-dep-riscv64-checks.patch": "0d1516c4655601174f5ee91a877ad1a0fcb287ed8df42f7e96297b47b03ea5e4",
+      "0008-source-stabilize-riscv64-musl-build.patch": "21a8ca86c77dd49140e29c0fd0a3d47a490b4d19d7617342db83567fa473b108",
+      "0009-disable-wasm-streaming-hooks-for-c-loop.patch": "c8658536cc46505cec35ab65f9d51daeba8cc5abac741f55496c65712c556731",
+      "0010-disable-inspector-profiler-for-riscv64-c-loop.patch": "4433d1077b59c325b19194fecefa4e33b5a586099fec0f4f999c82d053826128",
+      "0011-process-arch-add-riscv64.patch": "1a3e4ab498e83603a34016aab7f02d78fc21a0c7f61daa18cd282e8287d1ef1e",
+      "0012-cpu-features-add-riscv64-fallback.patch": "1ac5866560fed8cb37b107a7c684d501e77449c320eb0badc593fca97b12fab9",
+      "0013-disable-console-inspector-hooks-for-riscv64-c-loop.patch": "189822f2d07eeeec69b420b4c7657afdb12a37f01a90fc4e3150c85beca0d098",
+      "0014-disable-custom-inspector-dispatchers-on-riscv64.patch": "0c3c3d551a503d951baff9111057f16903e7c91831ab6e178b5e6ab37c3fab0d",
+      "0015-disable-jsc-profiler-builtins-on-riscv64.patch": "71741d5f58521247d14304667126f66befc1c912c9a677f370fe236adb981eaa",
+      "0016-node-vm-disable-jit-cached-data-on-riscv64-c-loop.patch": "5d63e5478d518c69f56e971b4b14b791ebe18bbc0195fd536cb3a33f00798488",
+      "0017-disable-performance-domjit-signature-on-riscv64-c-loop.patch": "1e2d0f77acfd11574db7b4ee212dc846d47b2d3c7adbe21301f3809fe0e96e2c",
+      "0018-fix-serialized-script-identifier-big-endian-path.patch": "2bcf9fbcf86d0bd37be3ac5145b85c7bac8fddfd87caffe68a5e1ec3fdbf6c52",
+      "0019-add-wtf-timer-fire-bridge-for-c-loop.patch": "e812c00feac0561de35fb4ca7aa37ce38280f47c84f0d8b246b4a62e6802f10b",
+      "0020-run-riscv64-smoke-test-under-qemu.patch": "26997fbd4d7fd6025565733df8ee61d982244b61be3bce7666ed9df35a0e86ce",
+      "0021-fix-riscv64-linux-open-flags.patch": "71613fdce702893ce2375d728b112fa32cb526f44277e516ae88a6c73fdb15e7",
+      "0022-zlib-riscv64-generic-kernels.patch": "0c39097e8f4513684ea25cb9eb83d4c48021b8e632c85c85faedf27ae9125f44"
+    },
+    "bun_patches_apply_status": "All 21 patches apply cleanly in sequence to oven-sh/bun @ bun-v1.3.14 via git apply (validate.sh confirms strict --check). Regenerated 2026-05-28 for the 1.3.14 source reorg: src/bun.js/{bindings,modules} -> src/jsc/{bindings,modules}, src/sys.zig -> src/sys/sys.zig, src/compile_target.zig -> src/options_types/CompileTarget.zig, src/crash_handler.zig -> src/crash_handler/crash_handler.zig, src/env.zig -> src/bun_core/env.zig, src/bun.js/bindings/CPUFeatures.zig -> src/crash_handler/CPUFeatures.zig. Patch 0008 adds the riscv64 toolchain overrides, external WebKit consumption, nested CMake cross settings, and Zig source enum guards; its 1.3.13 boringssl.ts hunk was dropped because 1.3.14's BoringSSL DirectBuild model self-guards per-arch asm (the wrong-target .S files assemble to empty objects via asm_base.h), so no OPENSSL_NO_ASM cmake arg is needed. Patches 0009-0020 disable JSC APIs unavailable in the C_LOOP/local-WebKit riscv64 artifact, fill riscv64 process/CPU feature fallbacks, fix riscv64-exposed source compatibility gaps, provide the WTFTimer fire bridge required by the local WebKit link, and run the riscv64 smoke test through qemu-riscv64-static; patch 0010's 1.3.13 BunInspector.cpp hunk was dropped because that file was removed upstream in 1.3.14. Patch 0021 fixes riscv64 Linux open flag constants so JS file entrypoints are not misclassified as missing directories.",
+    "bun_patches_target": {
+      "scripts/build/config.ts": ["0001", "0004", "0008"],
+      "scripts/build/flags.ts": ["0002"],
+      "scripts/build/zig.ts": ["0003"],
+      "scripts/build/source.ts": ["0008"],
+      "scripts/build/deps/webkit.ts": ["0004", "0008"],
+      "scripts/build/deps/tinycc.ts": ["0005"],
+      "scripts/build.ts": ["0006"],
+      "scripts/build/deps/lolhtml.ts": ["0007"],
+      "scripts/glob-sources.ts": ["0009"],
+      "scripts/build/bun.ts": ["0020"],
+      "src/bun_core/env.zig": ["0008"],
+      "src/crash_handler/CPUFeatures.zig": ["0008"],
+      "src/crash_handler/crash_handler.zig": ["0008"],
+      "src/options_types/CompileTarget.zig": ["0008"],
+      "src/install/npm.zig": ["0008"],
+      "src/bake/BakeGlobalObject.cpp": ["0009"],
+      "src/jsc/bindings/ZigGlobalObject.cpp": ["0009"],
+      "src/jsc/bindings/ZigGlobalObject.h": ["0009"],
+      "src/jsc/bindings/webcore/JSWasmStreamingCompiler.cpp": ["0009"],
+      "src/jsc/bindings/webcore/JSWasmStreamingCompiler.h": ["0009"],
+      "src/jsc/bindings/BunCPUProfiler.cpp": ["0010"],
+      "src/jsc/bindings/BunDebugger.cpp": ["0010"],
+      "src/jsc/bindings/BunProcess.cpp": ["0011"],
+      "src/jsc/bindings/CPUFeatures.cpp": ["0012"],
+      "src/jsc/bindings/ConsoleObject.cpp": ["0013"],
+      "src/jsc/bindings/InspectorBunFrontendDevServerAgent.cpp": ["0014"],
+      "src/jsc/bindings/InspectorBunFrontendDevServerAgent.h": ["0014"],
+      "src/jsc/bindings/InspectorHTTPServerAgent.cpp": ["0014"],
+      "src/jsc/bindings/InspectorHTTPServerAgent.h": ["0014"],
+      "src/jsc/bindings/InspectorLifecycleAgent.cpp": ["0014"],
+      "src/jsc/bindings/InspectorLifecycleAgent.h": ["0014"],
+      "src/jsc/bindings/InspectorTestReporterAgent.cpp": ["0014"],
+      "src/jsc/bindings/InspectorTestReporterAgent.h": ["0014"],
+      "src/jsc/modules/BunJSCModule.h": ["0015"],
+      "src/jsc/bindings/NodeVMScript.cpp": ["0016"],
+      "src/jsc/bindings/NodeVMSourceTextModule.cpp": ["0016"],
+      "src/jsc/bindings/webcore/JSPerformance.cpp": ["0017"],
+      "src/jsc/bindings/webcore/SerializedScriptValue.cpp": ["0018"],
+      "src/jsc/bindings/wtf-bindings.cpp": ["0019"],
+      "src/sys/sys.zig": ["0021"]
+    },
+    "webkit_patches": {
+      "0003-disable-dfg-ftl-on-riscv64.patch": "c00fe21a74ea35c8586cc380af6d03de89fef9d9bc8c4f0186dc7c629f0b9814",
+      "0004-riscv64-do-not-force-wasm-in-c-loop.patch": "031c9d4df85ecd313730d13a36a68bd4b222cc7e461d11b8e50ad0ff9bdec2cf",
+      "0005-domjit-effect-allow-no-dfg-c-loop.patch": "70da4f1f4a1b61ef8626cb07ad8899971efb9eea2f29bc7576881e54d42083e3",
+      "0006-disable-usewasm-when-webassembly-compiled-out.patch": "2e7a763abd922ce698cfc56ca916b6db262907115d0e250ad1b1aec4f845f918",
+      "0007-restore-dropped-includes-and-llint-fwd-decl.patch": "aebd3bcb6a7938dec40cdb9c4b4fd1abfe4170850abdf9e2e9edf268142714b1"
+    },
+    "webkit_recipes": {
+      "0001-cherry-pick-llint-riscv64.recipe": "8017bed5bf3f6fc22585b802c0016734ab48f0f70ddc675613c9b6930b8ea6b6",
+      "0002-cherry-pick-baseline-jit-riscv64.recipe": "4ee6709e6e30ccbdc1b50641dd924835fb1b28fd3d5b874625307fb699dc39b4"
+    },
+    "webkit_recipes_status": "Recipe files document the optional LLInt/Baseline cherry-pick chain. The publishable riscv64 artifact contract is C_LOOP-only until that chain is checked in as patch files and validated."
+  }
+}

package/scripts/bun-riscv64/run-build.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+#
+# Host-side wrapper for `docker build && docker run` of the
+# bun-riscv64 cross-compile pipeline.
+#
+# Usage:
+#   ./run-build.sh                       # build image + run cross-compile
+#   ./run-build.sh --no-cache            # rebuild image from scratch
+#   ./run-build.sh --baseline-jit        # experimental: requires realized WebKit patches
+#   ./run-build.sh --jobs 4              # cap parallel build jobs (default: nproc)
+#   ./run-build.sh --image-only          # just build the Docker image, don't run
+#   ./run-build.sh --shell               # drop into a shell inside the image
+#                                        # (for poking at the toolchain / sysroot)
+#
+# Reads pins from ./bun-version.json. The script is idempotent: re-running
+# without --no-cache reuses Docker layer cache for the heavy toolchain
+# install, so iterating on patches only re-runs the build steps.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$HERE"
+
+IMAGE_TAG="eliza/bun-riscv64-builder"
+NO_CACHE=""
+FORCE_CLOOP="1"
+JOBS=""
+IMAGE_ONLY=0
+SHELL_MODE=0
+RUST_CORE=0
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --no-cache) NO_CACHE="--no-cache"; shift ;;
+        --c-loop|--cloop) FORCE_CLOOP="1"; shift ;;
+        --baseline-jit) FORCE_CLOOP="0"; shift ;;
+        --jobs) JOBS="$2"; shift 2 ;;
+        --image-only) IMAGE_ONLY=1; shift ;;
+        --shell) SHELL_MODE=1; shift ;;
+        # Build the post-rewrite Rust-core bun (rust_core_port.target_commit +
+        # rust-core/ patch series) instead of the last-Zig tag. Default stays
+        # the validated Zig fallback.
+        --rust-core) RUST_CORE=1; shift ;;
+        -h|--help)
+            # Usage block lives in the file header (lines 3-17 of the
+            # leading comment, just below the shebang).
+            grep '^#' "$0" | sed -n '3,17p' | sed 's|^# \?||'
+            exit 0 ;;
+        *)
+            echo "Unknown arg: $1" >&2
+            exit 2 ;;
+    esac
+done
+
+# ─── Sanity checks ─────────────────────────────────────────────────────────
+command -v docker >/dev/null 2>&1 || {
+    echo "FATAL: docker not in PATH. Install Docker 25+ with buildx." >&2
+    exit 1
+}
+
+# Verify QEMU riscv64 binfmt is registered. Without this, `docker run
+# --platform linux/riscv64` works but our cross-build's QEMU-based smoke
+# test (qemu-riscv64-static bun --version) cannot execute.
+if [ ! -e /proc/sys/fs/binfmt_misc/qemu-riscv64 ] && \
+   [ ! -e /proc/sys/fs/binfmt_misc/qemu-riscv64-static ]; then
+    cat >&2 <<'NO_BINFMT'
+WARNING: No qemu-riscv64 binfmt_misc entry detected on the build host.
+The build will still cross-compile (host CPU runs clang, not the target
+binary), but the in-container smoke test (qemu-riscv64-static bun
+--version) will fail.
+
+Install the QEMU emulators system-wide first:
+
+    docker run --rm --privileged tonistiigi/binfmt --install riscv64
+
+Continuing — the build itself does not depend on this, only the post-build
+verification step does.
+NO_BINFMT
+fi
+
+# The Dockerfile vendors x86_64 toolchain binaries (Zig x86_64, bun x64
+# bootstrap), so the builder image MUST be linux/amd64. On amd64 CI hosts this
+# is native; on an arm64 host (Apple Silicon) it runs under emulation. Without
+# this, an arm64 host builds an arm64 image where the x86_64 bun bootstrap
+# fails with "rosetta error: failed to open elf .../ld-linux-x86-64.so.2".
+PLATFORM="linux/amd64"
+
+# ─── Build the image ───────────────────────────────────────────────────────
+echo "[run-build] building image ${IMAGE_TAG} (--platform ${PLATFORM})"
+docker build --platform "${PLATFORM}" ${NO_CACHE} -t "${IMAGE_TAG}" .
+
+if [ "$IMAGE_ONLY" = "1" ]; then
+    echo "[run-build] --image-only: stopping after image build."
+    exit 0
+fi
+
+# ─── Shell mode ────────────────────────────────────────────────────────────
+if [ "$SHELL_MODE" = "1" ]; then
+    echo "[run-build] dropping into shell inside ${IMAGE_TAG}"
+    exec docker run --rm -it \
+        --platform "${PLATFORM}" \
+        -v "$HERE:/work-host:rw" \
+        --entrypoint /bin/bash \
+        "${IMAGE_TAG}"
+fi
+
+# ─── Run the cross-compile ─────────────────────────────────────────────────
+mkdir -p "$HERE/dist"
+mkdir -p "$HERE/dist/src-cache"
+
+# Patch series: Zig fallback uses bun-patches/; --rust-core uses rust-core/
+# (0001 build-system + C_LOOP port, 0002 second-wave source gaps).
+PATCH_MOUNT="$HERE/bun-patches"
+if [ "$RUST_CORE" = "1" ]; then
+    PATCH_MOUNT="$HERE/rust-core"
+    echo "[run-build] --rust-core: building Rust-core bun (rust_core_port) from rust-core/ patches"
+fi
+
+DOCKER_RUN_ARGS=(
+    --rm
+    --platform "${PLATFORM}"
+    -v "$HERE/build.sh:/opt/build.sh:ro"
+    -v "$HERE/bun-version.json:/opt/bun-version.json:ro"
+    -v "$PATCH_MOUNT:/opt/bun-patches:ro"
+    -v "$HERE/webkit-patches:/opt/webkit-patches:ro"
+    -v "$HERE/dist:/artifact"
+    -v "$HERE/dist/src-cache:/work/src"
+)
+
+if [ -n "$JOBS" ]; then
+    DOCKER_RUN_ARGS+=(-e "JOBS=${JOBS}")
+fi
+if [ "$FORCE_CLOOP" = "1" ]; then
+    DOCKER_RUN_ARGS+=(-e "BUN_RISCV64_FORCE_CLOOP=1")
+fi
+if [ "$RUST_CORE" = "1" ]; then
+    DOCKER_RUN_ARGS+=(-e "BUN_RISCV64_RUST_CORE=1")
+fi
+
+echo "[run-build] starting cross-compile (this typically takes 30-90 minutes)"
+docker run "${DOCKER_RUN_ARGS[@]}" "${IMAGE_TAG}"
+
+# ─── Report ────────────────────────────────────────────────────────────────
+ARTIFACT="$HERE/dist/bun-linux-riscv64-musl.zip"
+if [ -f "$ARTIFACT" ]; then
+    SHA="$(sha256sum "$ARTIFACT" | awk '{print $1}')"
+    SIZE="$(du -h "$ARTIFACT" | awk '{print $1}')"
+    echo ""
+    echo "[run-build] SUCCESS"
+    echo "  Artifact : $ARTIFACT"
+    echo "  Size     : $SIZE"
+    echo "  SHA256   : $SHA"
+    echo "  Log      : $HERE/dist/build-log.txt"
+    echo ""
+    echo "Next: upload to a hosting target reachable from CI/dev hosts, then"
+    echo "      export ELIZA_BUN_RISCV64_URL='https://.../bun-linux-riscv64-musl.zip'"
+    echo "      before running the Android assemble step."
+else
+    echo "[run-build] FAILED — no artifact at $ARTIFACT"
+    echo "  Check $HERE/dist/build-log.txt for details."
+    exit 1
+fi