feat(scenarios): add Tessera state preparation

[92Infinitus92]

Stacked on #8 — Tessera is the same mechanism class as BisonFi (PMM, no IDL) and reuses the raw-layout engine it introduced.

• Everything declarative: 6 templates over the market account (fair value, depth, curve, halt, freshness, stale quote) plus a 26-market catalog carrying each market's mints, decimals and freshness limit.
• One builder (fair value): turns a human price into the two reciprocal atomic-ratio fields using the market's mint decimals, and pairs a persistent freshness override so the prepared quote stays live on the fork.
• One MCP tool, create_tessera_fair_value_scenario, on the generic scenario path. No protocol HTTP endpoints.
• 8 live gated tests against the deployed program (staleness boundary 0xffff, halt, ladder scaling), on shared live-test helpers.
• The three MCP helpers duplicate the pump branch's on purpose — they fold together when the branches converge.
• monitoring.yaml is documentation only: the program-upgrade fingerprint and the catalog refresh procedure.

Confidence Score: 5/5

The PR appears safe to merge.

Summary

The PR adds declarative Tessera state preparation, including raw-layout templates, market discovery, fair-value and depth builders, MCP tooling, and live protocol tests.

• Registers six Tessera templates for price, depth, curve, halt, freshness, and stale-quote preparation.
• Adds market validation and discovery through the caller-selected Surfnet RPC.
• Adds MCP tools for listing markets and creating fair-value or depth scenarios.
• Extends raw layouts with strided u8 writes for ladder-wide flags.
• Adds gated live tests for the pinned Tessera deployment and quote behavior.

Diagram

sequenceDiagram
    participant Client as MCP Client
    participant MCP as Surfpool MCP
    participant RPC as Selected Surfnet RPC
    participant Builder as Tessera Builder
    participant Studio as Scenario Studio
    Client->>MCP: Tessera tool call (surfnetPort)
    MCP->>RPC: Read market and mint accounts
    RPC-->>MCP: Current account state
    MCP->>Builder: Validate and build overrides
    Builder-->>MCP: Scenario
    MCP->>Studio: Stage scenario
    Studio-->>Client: Editor URL

Loading

_{Reviews (13) · Last reviewed commit: "docs(tessera): say that the freshness ov..."}

[github-actions]

• P1 – MCP tool ignores the selected surfnet port (mod.rs): fetch_surfnet_accounts always connects to DEFAULT_RPC_PORT. start_surfnet may choose 18899, 28899, etc., and stores that port in self.surfnets; in those cases the Tessera tool fails or reads an unrelated process. Accept a surfnet/RPC parameter or resolve the active port from self.surfnets.

[github-actions]

No actionable findings in the reviewed diff.

The previously reported RPC-target issue is fixed at 8539d42: surfnet_port is caller-selectable and used for both market and mint account reads.

Tests could not run because Rustup attempted to write outside the permitted workspace.

[github-actions]

• [P2] fair_value.rs:183-190 silently truncates prices with more precision than the atomic ratio supports. The scenario label still reports the requested price although a lower price is applied. Reject non-zero discarded digits or explicitly report the normalized price.

[github-actions]

No actionable issues found in the PR changes.

Focused tests could not run because Rustup attempted to write under the read-only /home/runner/.rustup directory. Static review covered the builder, MCP flow, templates, registry, and test gating.

[github-actions]

No concrete bugs found in the specified PR range.

One testing improvement: add a local RPC test for list_tessera_markets covering local overrides and a nondefault Surfnet port. The current discovery test queries mainnet directly, so it doesn’t verify those advertised behaviors.

Tests could not run: the pinned toolchain required a write outside the sandbox, and the installed toolchain’s offline dependency cache lacked bincode.

[github-actions]

• [P1] Preserve the selected Surfnet when staging scenarios — mod.rs:1142, also line 1181. Both Tessera builders read accounts using surfnet_port, then discard it when calling stage_scenario. Neither the stored scenario nor the editor URL retains that target, so a scenario derived from port 18899 can be played against Studio’s default Surfnet. Carry the target through staging and playback, or reject unsupported ports until routing is implemented. Add a regression test using two Surfnet instances with different market states.

Static review only; live tests were not run.