BOHICA-LABS / BOHICA-LABS/vsdd-factory

bug(dispatcher): FUEL_EXHAUSTED advises raising fuel_cap, a registry field the plugin documents as not implemented

Open
#809 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Symptom

Every `Edit` to a large `.factory/` artifact produces:

```
fail-closed: FUEL_EXHAUSTED: fuel cap of 20000000 units exhausted;
raise fuel_cap or reduce payload size
```

from `validate-factory-path-root`, `validate-input-hash`, and `validate-template-compliance`. Reproduced on every edit to two artifacts across a full working session (a 616 KB decision note and a ~515 KB story index). `validate-changelog-monotonicity` continues to run throughout.

## The defect is the remedy, not the exhaustion

The message instructs the operator to `raise fuel_cap`. **That field is not implemented.** From the shipped `hooks-registry.toml` (lines 681–687), verbatim:

```
# No fuel_cap field: the per-plugin fuel_cap registry field (ADR-035 §Decision 5,
# ADR-039 §Decision 2) is not yet implemented — ADR-039 Phase 1 (registry fuel_cap
# schema extension) has not shipped. ... Until then the only available lever is
# the global InvokeLimits::default() cap
```

So of the two remedies the error offers, one names an unimplemented field and the other — "reduce payload size" — is unavailable to an artifact that must grow as it accumulates content. Shrinking it requires writes, which trip the same hooks.

## The headroom has already been measured, and a safety claim retracted

`hooks-registry.toml` lines 674–677, verbatim:

```
# NOTE: max_bytes caps are
# NOT calibrated against the fuel budget — BC-5.39.010 v1.15 RETRACTED that claim
# as false (measured fuel consumption ~99.21% of the 10M-instruction budget at
# typical artifact sizes, i.e. near-exhaustion, not comfortable headroom).
```

**Deliberately not over-claiming this number:** that 99.21% was measured against a **10M** budget, while the live runtime cap is **20M**. I have not measured current consumption at typical sizes and do not claim the figure transfers. The two data points bracket the problem without extrapolation — near-exhaustion at typical sizes under 10M, and actual exhaustion at 616 KB under 20M.

## The existing mitigation is scoped to one filename while the budget is global

`validate-state-size.sh` (lines 123–128) blocks above 4000 lines and warns above 3500, with the reason `"WASM fuel exhaustion risk per D-442(e)"` — for `lessons.md` only.

Of the 38 shell hooks shipped in `hooks/`, exactly **2** reference a line count at all (`validate-state-size.sh`, `precompact-flush-prune.sh`). The 616 KB note that exhausts the budget is 4112 lines — past the threshold the plugin itself treats as dangerous — and sits in a directory with no guard.

## A hypothesis tested and disproved

Recorded so it isn't re-run: fuel use is **not** simply proportional to how much of the target file a hook reads. `validate-factory-path-root` is 59 lines with no whole-file read and exhausts; `validate-changelog-monotonicity` is 195 lines with a whole-file read and survives. All four route through `legacy-bash-adapter.wasm`, so the difference is per-script cost or early-exit structure, not the adapter's payload handling. I did not identify the actual cause; early exit is the untested candidate (`validate-changelog-monotonicity` likely returns immediately on a file with no changelog table).

## Asks

1. Ship ADR-039 Phase 1, or change the message so it stops naming an unimplemented field.
2. Emit a signal distinguishable from success when a hook is skipped for fuel. Right now a fuel-skipped validator and a clean pass are indistinguishable in the transcript, so validation coverage is silently lost on exactly the largest, most-edited artifacts.
3. Generalize the `validate-state-size` guard beyond `lessons.md` to any `.factory/` artifact past the same threshold, or document why `decisions/` and `stories/` are exempt.

## Environment

Plugin `1.0.0-rc.24`, `hooks-registry.toml` `schema_version = 2`, dispatcher `factory-dispatcher` (single native binary, all hooks per event), wasmtime 46.0.2. ADR-035/039/042 are cited by the registry but not shipped in the plugin, so I could not read them.

Contributor guide

Open the contributing guide

Research direction

The error originates in the dispatcher's fuel exhaustion logic, likely in the WASM adapter or hook runner. Examine the code generating the FUEL_EXHAUSTED message (search for that string) and the registry handling for fuel_cap. Review the hooks-registry.toml schema and the ADR-039 references. Testing changes requires understanding the hook execution flow and the artifact validation pipeline.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, shell, wasm
Domain
backend-api-design, devtools
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.