runtime: meter fuel calls in metered stores

[Wavesonics]

chasm has no instruction budget and no way to interrupt a running call. For apps embedding chasm in order to run 3rd party code like plugins that is often a feature they want.

I've implemented an instruction budge by rewriting each module when I load it, to decrement a global counter at every function entry and loop header, which adds eight instructions to every iteration. This costs me about 26% performance degradation.

Integrating a solution directly into Chasm is much more efficient:

A store created with store(meterFuel = true) now compiles one FuelCheck instruction at each function entry and at each loop's branch target, taking from the store's Fuel.

setFuel, remainingFuel, and interrupt drive it: running out traps with FuelExhausted, and an interrupt from another thread traps the running call with Interrupted at its next check. An interrupt made while no call runs is dropped.

Unmetered stores compile no checks, so existing embedders are unaffected.

On a grammar-checking plugin (Harper, compiled to Wasm) checking 40 paragraphs on the JVM:

Fuel metering	Time
None	0.83 to 0.88 s
Rewriting workaround	1.12 to 1.16 s
Native fuel	0.94 to 0.97 s

Fixes #123 & #122, possibly fixes #86

[CharlieTap]

I think maybe something like addFuel would be more flexible, as you could top it up rather than replacing the remaining each time. With some sensible checks like:

fun addFuel(
    store: Store,
    amount: Long,
): ChasmResult<Unit, ChasmError.ExecutionError> {
    val fuel = store.store.fuel

    if (amount < 0L || !fuel.metered) {
        return ChasmResult.Error(
            ChasmError.ExecutionError(
                "Fuel must be non-negative and metering must be enabled",
            ),
        )
    }

    fuel.remaining += amount.coerceAtMost(Long.MAX_VALUE - fuel.remaining)
    return ChasmResult.Success(Unit)
}

I don't if its of any use but a resetFuel might be a good complementary function?

[CharlieTap]

I would pull this (and the other interrupt related parts) out and make them a separate PR which is agnostic of metering

[CharlieTap]

I would decrement post check:

if (fuel.remaining <= 0L) {
    throw InvocationException(InvocationError.FuelExhausted)
}
fuel.remaining--

This preserves zero after exhaustion

[CharlieTap]

This can go to zero once we addFuel

[CharlieTap]

It would be nice to have this as its own function, like:

internal fun FunctionCompilationContext.emitFuelCheck() {
    val fuel = compiler.fuel ?: return
    emit(AdminInstruction.FuelCheck) {
        FuelCheckDispatcher(it, fuel)
    }
}

[CharlieTap]

Typically we commit both a .wasm and a .wat fixture rather than embedding the binary directly. That lets me review the source. You could combine these modules into one fixture and call different exports through testRunner, as in [TypeSystemCorrectnessTest](https://github.com/CharlieTap/chasm/blob/main/chasm/src/commonTest/kotlin/io/github/charlietap/chasm/integration/TypeSystemCorrectnessTest.kt#L15-L41).

If testRunner isn’t flexible enough for the fuel setup, you can load and instantiate the fixture directly—[PrepareFunctionTest](https://github.com/CharlieTap/chasm/blob/main/chasm/src/commonTest/kotlin/io/github/charlietap/chasm/integration/PrepareFunctionTest.kt) shows that approach.

[CharlieTap]

Given we move to addFuel we could do with a few extra cases:

• A fresh metered store has zero fuel and traps on invocation; an exactly sufficient allowance succeeds and leaves zero.
• addFuel preserves the existing balance, adding zero changes nothing, and additions reaching or exceeding Long.MAX_VALUE saturate correctly.
• Negative additions and additions to unmetered stores return an error without changing the balance.
• After exhaustion, adding fuel allows a finite function to complete successfully. The current refill test runs another infinite loop, so it doesn’t quite establish this.
• A looping start function exhausts fuel during instantiation.

[CharlieTap]

Similarly this should probably have a check if fuel.metered is set just to steer correct use of the api.

[Wavesonics]

thanks for all the feedback @CharlieTap I'll address it tonight!

[CharlieTap]

Hey 👋🏼

Thank you for this! I like the approach as It think it's rigorous enough without getting into really granular cost estimation. Just a few comments to steer the API and get the implementation a little more consistent with the existing source

[Wavesonics]

I think I've addressed all of your feedback. A few notes:

• I switched store to the config object pattern used elsewhere: store(StoreConfig(meterFuel = true)). The plain store() is unchanged, so the 2.0.0 API is unaffected.
• I added resetFuel alongside addFuel.
• The fuel tests load the fixtures directly, like PrepareFunctionTest, since each store needs a config and fuel before the call, which testRunner doesn't support.
• I pulled interrupt out of this PR. I'll open a separate PR stacked on this one with a different approach that doesn't depend on metering and is turned on through StoreConfig.

[CharlieTap]

Thank you for this it's much appreciated! I'm planning a release next weekend so lets see if we can get the interrupt parts over the line, if you need something in the interim I can publish a snapshot for you