[dezren39]

Summary

Phase 11 task F11.6. Fuel is the guests' main performance ceiling, and it was invisible.

• WorldInstance records fuel used per guest call (init, update, view, layout, records, wants, snapshot, restore): calls, total, max, last. A fuel-exhausting trap records the full limit. Fixed array, no locking, never journaled, never on the wire.
• id world measure --module FILE.wasm --seed N [--input HEX]... [--width W --height H] prints one JSON report: module size, the fuel limit, per-call stats, and the worst call as a percent of the limit.
• checked_in_examples_stay_within_fuel_budgets fails when any call exceeds its baseline by more than 25 percent, and when a call has no budget row. Every example module must be at most 1 MiB. The failure message says to re-baseline deliberately.

Design record: doc/2026-10-17T15-30-00Z_feature_world_perf_budgets/. Stacked on #234.

Finding: territory overflows the fuel limit with six or more seats

Worst call as a share of the 10M limit: roc-counter 0.04%, tic-tac-toe 0.14%, roc-chat 0.90%, lounge 1.95%, roc-grid 9.8%, roc-screen 11.9%, territory 78.0% with two seats. Each seat adds about 0.8M, so six or more seats run out of fuel, and a view that runs out of fuel poisons the world. Territory allows eight seats. My earlier claim that the styled view fits with all eight seats was wrong; that measurement used few seats. The fix is the next PR; the budget table only guards the two-seat baseline, which the record flags.

Validation

• cargo test --lib: 1335 passed, 5 ignored (the subagent's run). I re-ran sandbox:: (27 passed, 1 ignored) and the measure tests (2 passed).
• cargo fmt --check: clean. Clippy via the rustup 1.97.0 cargo exits 0; plain cargo clippy fails with E0514 as before.

Summary by CodeRabbit

• New Features
  • Added the offline id world measure command to report guest-call fuel usage, including call counts, totals, maximums, and usage relative to the fuel limit. It supports repeatable inputs and optional viewport dimensions.
  • Added per-call fuel metrics for world instances, including calls that trap.
• Documentation
  • Added guidance on measurement coverage, interpreting results, and fuel-budget baselines.
• Tests
  • Added automated checks for example fuel budgets and module size limits.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: b8511642-3b43-465e-a71e-be1fb9476944

📥 Commits

Reviewing files that changed from the base of the PR and between 13f202d and 6bfe305.

📒 Files selected for processing: 2

• pkgs/id/src/cli.rs
• pkgs/id/src/commands/world.rs

+----------------------------------------------------------------------------------------------------------------------------------------------+
| Eliminate effects between unrelated things. Design components that are self-contained, independent, and have a single, well-defined purpose. |
+----------------------------------------------------------------------------------------------------------------------------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 81febeba-6972-44a2-ac7b-088d89d48775

📥 Commits

Reviewing files that changed from the base of the PR and between 228019a and 13f202d.

📒 Files selected for processing: 4

• doc/2026-10-17T15-30-00Z_feature_world_perf_budgets/2026-10-17T15-30-00Z_feature_world_perf_budgets.md
• pkgs/id/src/cli.rs
• pkgs/id/src/commands/world.rs
• pkgs/id/src/sandbox.rs

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.

📝 Walkthrough

The sandbox now tracks per-call guest fuel use. The id world measure command runs Wasm calls and reports their metrics. Scripted tests measure seven examples and check per-call fuel budgets and module size.

Changes: Guest fuel measurement

Layer / File(s)	Summary
Track guest-call fuel pkgs/id/src/sandbox.rs, doc/2026-10-17T15-30-00Z_feature_world_perf_budgets/2026-10-17T15-30-00Z_feature_world_perf_budgets.md	The sandbox tracks counts, total, maximum, and latest fuel for eight guest-call kinds. It records fuel for trapped calls and includes tests for accounting and error cases.
Measure a Wasm world pkgs/id/src/cli.rs, pkgs/id/src/commands/world.rs, doc/2026-10-17T15-30-00Z_feature_world_perf_budgets/2026-10-17T15-30-00Z_feature_world_perf_budgets.md	The sandbox-gated id world measure command accepts a module, seed, repeated inputs, and optional viewport dimensions. It runs the measurement calls and prints a JSON report with per-call metrics.
Check example fuel budgets pkgs/id/src/sandbox.rs, doc/2026-10-17T15-30-00Z_feature_world_perf_budgets/2026-10-17T15-30-00Z_feature_world_perf_budgets.md	Scripted workloads measure seven examples. Tests enforce per-call budgets and a 1 MiB module limit. The documentation lists baseline measurements and describes the budget method and limitations.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI as id world measure
  participant Measure as measure_module
  participant Instance as WorldInstance
  participant Guest as Wasm module
  CLI->>Measure: module, seed, inputs, optional dimensions
  Measure->>Instance: instantiate module
  Measure->>Instance: invoke measurement calls
  Instance->>Guest: execute guest calls
  Instance-->>Measure: per-call fuel metrics
  Measure-->>CLI: JSON report

Loading

Merge Risk: ⚪ Minimal · up to 13f20

The fuel metrics, offline measurement command, and scripted budgets have no identified issue that prevents merging.

Security architecture risk: 🔵 Low · up to 13f20

The change adds diagnostics without weakening the existing guest execution limits or granting guests additional capabilities. No introduced or worsened security concern was established. The budget checks cover scripted scenarios, not every permitted world state.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The new entrypoint exposes caller-selected Wasm and events to a fresh local sandbox instance, not to an existing tenant or hosted-world session. Its examined failure scope is the measurement process and instance; no new cross-service authority was identified.

Trust Boundaries and Controls

• observed — Measurement uses the existing default limits: 10 million fuel per invocation, 16 MiB module and linear-memory limits, and 1 MiB messages. Compilation enables fuel consumption and rejects guest imports. Hex decoding rejects odd-length, over-limit, and non-hex inputs before guest execution.

Resilience and Maintainability Implications

• observed — Accounting does not govern guest authority or model assignment. Update and restore retain success-before-commit ordering, failed operations poison the instance, and absent optional exports remain uncounted. Layout now also poisons on post-call validation failures, strengthening containment relative to the base.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 68.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 44 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main changes: per-call guest-fuel measurement and budget enforcement.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 68.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 44 functions across 3 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}