feat(scenarios): add HumidiFi state preparation

[92Infinitus92]

HumidiFi markets can now be discovered and prepared through the existing scenario and MCP paths. Adds fair-value, persistent-freshness, stale-quote and liquidity scenarios, with an explicitly selected market and guarded raw-layout writes. Fair-value scenarios fetch the market before Play, then keep its quote fresh locally.

Stacked on #15 (feat/scenarios/raw-layout). Reuses its raw-layout materializer and registry loader, adding an optional eight-byte XOR mask for HumidiFi account fields.

Validation:

• cargo fmt --all -- --check
• cargo test --offline --workspace --features surfpool-core/ignore_tests_ci -- --test-threads=1: 943 passed, 0 failed, 66 ignored.
• cargo test --offline -p surfpool-core --features integration-tests tests::humidifi -- --test-threads=1 --nocapture: 10 passed, including deployed-program swap and exact account-byte checks.
• cargo clippy --offline --workspace --all-targets: exit 0, existing warnings.
• cargo build --offline --release --features supervisor_ui: exit 0.

The live integration tests execute the deployed HumidiFi program in the test VM through the documented DFlow test wrapper.

Confidence Score: 5/5

The PR appears safe to merge with no outstanding actionable findings.

Findings

1.  Freshness expires after one write ▶

Fix with agent prompt

### Issue 1
crates/core/src/scenarios/protocols/humidifi/v1/fair_value.rs:246-255
The builder schedules `last_update_slot` only once at slot 0. If the scenario executes after `max_staleness_slots`, no later override refreshes the quote, so HumidiFi rejects it as stale. This also affects the liquidity builder, which uses the same helper, and contradicts the documentation that says scenarios running past the freshness window refresh at a later slot. Schedule additional freshness overrides within the market's window or otherwise preserve the refresh behavior.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR adds HumidiFi market discovery and state preparation through the existing scenario and MCP interfaces.

• Adds guarded XOR-aware raw-layout templates for fair value, freshness, stale quotes, and vault liquidity.
• Validates market ownership, schema version, mint metadata, and vault relationships before building scenarios.
• Exposes market discovery and scenario creation through MCP and shared scenario types.
• Adds unit and live integration coverage for account encoding, discovery, swaps, staleness, and liquidity changes.
• Clarifies that builder-generated freshness is applied once at Play and must be extended explicitly for scenarios spanning the staleness window.

Diagram

sequenceDiagram
    participant Client
    participant MCP
    participant SurfnetRPC
    participant Builder
    participant ScenarioEngine
    Client->>MCP: List HumidiFi markets
    MCP->>SurfnetRPC: getProgramAccounts
    SurfnetRPC-->>MCP: Candidate market accounts
    MCP->>MCP: Validate layout, schema, mints
    MCP-->>Client: Explicit market choices
    Client->>MCP: Create fair-value or liquidity scenario
    MCP->>SurfnetRPC: Read market, mints, and optional vaults
    SurfnetRPC-->>MCP: Hydrated account snapshot
    MCP->>Builder: Validated accounts and requested values
    Builder-->>MCP: Scenario overrides at preparation slot
    MCP->>ScenarioEngine: Register scenario
    Client->>ScenarioEngine: Play
    ScenarioEngine->>ScenarioEngine: Apply guarded raw-layout and balance writes

Loading

_{Reviews (7) · Last reviewed commit: "docs(humidifi): say that the freshness o..."}

[greptile-apps]

Freshness expires after one write

The builder schedules last_update_slot only once at slot 0. If the scenario executes after max_staleness_slots, no later override refreshes the quote, so HumidiFi rejects it as stale. This also affects the liquidity builder, which uses the same helper, and contradicts the documentation that says scenarios running past the freshness window refresh at a later slot. Schedule additional freshness overrides within the market's window or otherwise preserve the refresh behavior.

Prompt To Fix With AI

This is a comment left during a code review.
Path: crates/core/src/scenarios/protocols/humidifi/v1/fair_value.rs
Line: 246-255

Comment:
**Freshness expires after one write**

The builder schedules `last_update_slot` only once at slot 0. If the scenario executes after `max_staleness_slots`, no later override refreshes the quote, so HumidiFi rejects it as stale. This also affects the liquidity builder, which uses the same helper, and contradicts the documentation that says scenarios running past the freshness window refresh at a later slot. Schedule additional freshness overrides within the market's window or otherwise preserve the refresh behavior.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[92Infinitus92]

@greptileai The behaviour is deliberate, but the doc comment you quoted was wrong, so thanks for catching it.

Every override the builder emits sits at relative slot 0, so the scenario it produces is one slot long. Studio's Play pauses the clock at that slot before registering the scenario, so a swap sent there reads an age of zero. There is no later slot in the scenario to schedule a second refresh into.

Repeating the write is also not something the engine can do on its own any more. Base commit 475b48e removed override persistence, and the scenarios README now carries the rule: an override is applied once, and its result stays in the account until a transaction or another override writes it again.

So what needed fixing was the sentence, which claimed a scenario past the market's window refreshes itself. Nothing does that. Fixed in bf0758a: the comment and the README now say the builder writes freshness once, and a scenario extended past the window needs a second freshness override of its own. The same wording is corrected on the GoonFi and Tessera branches.

[greptile-apps]

That clarification is correct. The builder intentionally creates a one-slot scenario, Play pauses at the preparation slot, and the one-time freshness write is sufficient for the intended swap. Since override persistence was removed, automatic refresh is not available; scenarios that extend beyond the staleness window must add their own later freshness override. Commit bf0758a corrects the HumidiFi comment and README, so this finding is resolved and no code change is needed.