FrankenEngine: a native Rust runtime for adversarial JavaScript extensions

The problem FrankenEngine targets: extension code you cannot audit at runtime

Most JavaScript extension hosts sit on top of an existing engine. You embed V8, JavaScriptCore or QuickJS and then try to wrap the host boundary with permissions. FrankenEngine rejects that shape. Its first constitutional rule is native-only core execution, with no V8, JSC or QuickJS bindings, and the README gives the reason plainly: binding-led runtimes ship with megabytes of upstream unsafe C++ or Zig that sit outside the information-flow-control and capability algebra, and retrofitting a type-safe authority membrane around that is, in the project's wording, structurally lossy.

The audience follows from that. This is for people who need to reason about what an untrusted extension did after it ran, not just stop it while it runs. The README frames the target as adversarial JavaScript and TypeScript extension workloads, and the repository carries examples such as 21_live_capability_rejection, 17_information_flow_confinement and 26_non_exfiltration_certificate. If your problem is "run a plugin safely enough", a hardened embed of an existing engine is cheaper. If your problem is "produce evidence that a specific decision was made under a specific policy, and replay it", the design here is aimed at you.

How the lowering pipeline, IFC labels and hostcall gates fit together

The README describes a lowering pipeline that owns parser-to-scheduler semantics in Rust, under `#![forbid(unsafe_code)]`. Intermediate representations are staged: information-flow-control labels are computed at IR2, and capability checks gate every hostcall edge. That ordering matters. A label assigned before the program reaches the scheduler means the scheduler does not have to re-derive authority from call-site context, and every edge out of the runtime is a checkpoint rather than a convention.

Determinism is a separate mechanism, not a property of the scheduler. Replay captures the IR3 program, the policy snapshot, the model snapshot, the evidence stream and a randomness transcript. The README names a coverage gate, `bd-2488a`, which fails closed unless every high-severity decision in a declared inventory replays byte-for-byte. That is a stronger statement than "the run is reproducible": the gate has an inventory, and a decision class outside the inventory is not covered by the claim.

Evidence is the third layer. Every evidence entry is Ed25519-signed with the originating runtime's key, and entries carry chained `prev_hash` fields so retroactive edits are detectable. The artifact bundle ships a `run_manifest.json` with schema id, host facts, content hashes and operator-verification commands. The README's point is that the rules compose: a containment action is replay-anchored and signed, so a counterfactual replay under a different policy snapshot reconstructs what would have happened, and that result is itself signed evidence.

Installing frankenctl and running a first signed decision receipt

The README states that prebuilt `frankenctl` binaries ship via GitHub Releases for Linux x86_64 and macOS Apple Silicon, with a checksum-verified installer. The installer script is `install.sh` at the repository root, and the README describes it as a `curl | bash` installer that falls back to a source build on other platforms. There is also an `install.ps1` in the repository listing for Windows.

Because the installer is fetched and executed, the sensible first step is to read it rather than pipe it blind. The README does not spell out an environment variable or flag to skip checksum verification, so treat the verification as part of the install rather than something you tune.

curl -fsSL https://github.com/Dicklesworthstone/franken_engine/releases/download/v0.1.0/install.sh -o install.sh
less install.sh
bash install.sh

After install, the repository's example directories are the practical entry point. `examples/02_signed_decision_receipt` is the smallest example that exercises the evidence path, and `examples/11_cli_workflow_smoke` is a CLI smoke test. The README does not publish the exact subcommand names for these examples, so read the example's own files before running anything; the repository layout is the authority here, not this article.

If you are building from source instead, the workspace is a Cargo workspace at edition 2024 and workspace version `0.1.0`. The README notes that the standalone source or release build resolves only workspace and registry sources and requires no sibling checkout, tracked as `bd-gw4cg`, and points to the Standalone Mode section for details.

cargo build --release
cargo test

One version caveat before you pin anything. The README states that current `main` stages `frankenengine-core` and `frankenengine-engine` at an unreleased `0.2.0` compatibility boundary, and that this does not create a `v0.2.0` tag or release. If you need a released artifact, `v0.1.0` is the only one listed.

The claim-to-proof gate is the most interesting idea here, and the least finished

FrankenEngine ships a documentation gate. Running `./scripts/run_claim_to_proof_matrix_gate.sh ci` checks the README against `docs/claim_to_proof_matrix_v1.json`. Claims classified `hypothesis` or `target` must say so explicitly, and absolute-superiority terms including `guarantees`, `unbreakable`, `always`, `proves`, `category-defining` and `>=Nx faster` require backing artifacts. When a sentence overstates its state, the gate emits exact `downgrade_text`.

This is unusual and worth taking seriously as a design idea: the README is treated as a build artifact with a truth ledger behind it, and the project's own status section uses three qualifiers, OBSERVED, TARGETED and HYPOTHESIS, with binding meaning under the runtime charter.

The limitation is stated in the same section. Continuous CI enforcement and automatic re-execution of every producer are not established. So the gate exists and can be invoked, but nothing in the README says it runs on every change. A gate you have to remember to run is a weaker guarantee than the surrounding prose suggests, and that gap is the single thing I would check before trusting any status claim on a given revision.

Where FrankenEngine is the wrong tool

The README is direct: this is research-grade infrastructure, not a packaged product. The automation surfaces ship in advisory-only mode, and the shadow daemon and related automations cannot execute live mutations or production deployments until adoption gates are verified green, per `docs/SHADOW_DAEMON_PROOF_STATE.md`.

That rules out a set of use cases. If you need a plugin host today for a shipping product, the advisory-only constraint on automations and the absence of a packaged product mean you are adopting an unshipped control surface. If you need broad platform coverage, the prebuilt binaries are Linux x86_64 and macOS Apple Silicon, with a source-build fallback elsewhere; that is narrower than a typical embeddable engine. If you need a stable dependency boundary, note that `main` stages an unreleased `0.2.0` compatibility boundary, so building from `main` and building from the `v0.1.0` release are not the same thing.

The Cargo manifest also documents a real failure that already happened. A `[patch.crates-io]` block substituting a local `fsqlite` was removed on 2026-07-25 under `bd-h5cl7`. The comment records that the patch applied silently because `sqlmodel-frankensqlite` declares `fsqlite = "0.1.18"` and Cargo's 0.x rules admit `0.1.19`, which shipped a breaking sync-to-async API change; 33 sync call sites then met Futures, the default build went red, and 7 of 16 OBSERVED claims became unverifiable because their verification commands are default-feature builds. The manifest tells you not to reintroduce a patch block without reading that bead and `scripts/check_patch_version_consistency.py`. That is a candid and useful piece of history, and it also tells you how tightly the observed claims are coupled to the default build staying green.

FrankenEngine versus embedding V8 or QuickJS

The obvious alternative is to embed an existing engine and put your permission model at the host boundary. The difference is not performance, it is where authority lives. With a binding-led host, the engine internals are outside your capability algebra; you gate the API surface you expose and accept that the code below it is not modelled. FrankenEngine inverts that: labels are computed at IR2 inside the pipeline, and capability checks gate every hostcall edge, so the authority model covers the path from parse to hostcall rather than starting at your wrapper.

The cost is that you are not reusing a mature engine. A V8 or QuickJS embed inherits years of JIT work, platform coverage and ecosystem tooling. FrankenEngine has one published release, `v0.1.0`, dated 2026-05-29, and its own README calls it research-grade. The last push to the default branch was on 2026-05-29. If your requirement is throughput on ordinary workloads, the mature embed wins on the evidence available. If your requirement is a replayable, signed record of a containment decision, the mature embed has no equivalent mechanism, and that is the trade the project is making.

Licence, upgrade cost and what a version bump actually involves

The repository's LICENSE file is present, and the workspace manifest declares `license = "MIT"` for the workspace package. The repository metadata reports the licence as NOASSERTION, which means the automated classifier could not confirm a standard identifier. Those two facts are not in conflict, but they are also not the same claim, and anyone who needs certainty should read the LICENSE file and the per-crate manifests rather than the workspace default. I am not giving legal advice; the discrepancy is simply worth resolving before you depend on it.

The upgrade picture is the more practical concern. There is one release, `v0.1.0`, and `main` stages an unreleased `0.2.0` compatibility boundary across `frankenengine-core` and `frankenengine-engine`. The workspace pins `edition = "2024"`, so toolchain age is a real constraint on the build side. The `fsqlite` incident in the manifest comment is the clearest signal about upgrade cost: a patch-level bump in a transitive dependency broke the default build and invalidated a majority of the observed claims, because those claims are verified by default-feature builds. A project whose evidence is produced by the default build has to keep that build green, and the README shows that is not automatic.

Editorial conclusion

Adopt FrankenEngine only if you are evaluating containment design for untrusted extension code and can read the charter and claim-to-proof matrix alongside the source. Do not adopt it as a production JavaScript sandbox: the README calls it research-grade infrastructure, automation surfaces are advisory-only, and continuous CI enforcement of the claim gate is not established. Verify first that frankenctl resolves on your platform, that the claim gate script passes on the revision you intend to pin, and that the replay coverage gate's declared inventory covers the decision classes you care about.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes