What-if Research

What-if Research translates a reviewed question and explicit assumptions into a bounded hypothetical experiment. Deterministic private studies produce the numeric outcomes; the model interprets a constrained finding catalog. Research output carries neither financial execution nor publication authority.

Research is a durable WHAT_IF_RESEARCH agent workflow, subject to enabled workspace policy, provider configuration, worker coverage and the initiating user's current permissions. It requires ai:read, ai:generate, vault:read and simulation:run. See AI agents for admission, controls and lifecycle states.

Planning and execution#

There are two entry paths:

Planning can propose a supported objective and scenario hypotheses. Starting portfolio, starting depth, inventory, seed and modeled horizon come from explicit user assumptions. Missing values remain missing. Planning reserves model work but zero study compute; it does not run a simulation before confirmation.

A planning admission body has this structure:

{
  "kind": "WHAT_IF_RESEARCH",
  "mode": "PLAN",
  "question": "Compare supported capital plans under a seller shock using assumptions I will review.",
  "subject": {
    "issuerIntentId": "your-current-issuer-intent-id",
    "expectedResourceVersion": "the-exact-returned-resource-version"
  },
  "assumptions": {}
}

Replace the subject placeholders with values from a current authorized source read. An empty assumption document intentionally leaves required inputs missing. It cannot authorize execution.

Review a planning proposal#

Read GET /api/liquidity-studio/v2/agent-runs/{runId}/research-planning. The typed proposal binds its question, source, assumptions, model hypotheses and provenance to a proposalHash.

• NEEDS_INPUT exposes missing values, validation issues or unsupported intent. Supply the required assumptions and review the next proposal.
• NEEDS_REVIEW means the proposal is structurally ready for explicit confirmation. It is not execution authorization.

Each field identifies whether it came from the user, a model-proposed hypothesis or missing input. Unsupported intent reported by the model blocks confirmation; this is model classification, rather than proof that every unsupported meaning in free text has been detected.

REVISE_ASSUMPTIONS replaces the whole user assumption document. It does not merge hidden defaults or change the original question and source. Send the current questionId, proposalHash and complete replacement assumptions to the command endpoint with the current run If-Match version and stable idempotency key. At most four planning model attempts are admitted; a final proposal can be reviewed even when no further revision is available.

CONFIRM_RESEARCH requires the exact current proposal, current source version, acceptance of model hypotheses and all twelve returned capability acknowledgements. The server rechecks the settled model receipt, source, membership, idempotency and reservations. It atomically completes the planning run and admits one execution successor. A failed successor admission rolls back the handoff. Keep and follow successorRunId; the completed planning run is a handoff record, rather than a computation report.

Explicit experiment contract#

The execution request uses kind: "WHAT_IF_RESEARCH", the reviewed subject and an experiment with:

Scenario inputs use the quantitative engine's strict schema and horizon checks. Research rejects LARGE_BUYER because that engine does not model positive buyer price impact. It does not silently turn an unsupported request into a nearby scenario. Preserve exact amount strings; converting them to JavaScript floating-point numbers can lose financial precision.

Studies and progress#

The workflow captures the admitted issuer-intent source, compiles a frozen protocol and dispatches private quantitative jobs. A baseline plus at most three alternatives yields up to four scenario trials. Each scenario evaluates the same five engine-generated capital-plan variants.

The parent enters WAITING_FOR_CHILDREN while the private studies run. Use /research-progress to inspect status and /research-trials/{trialKey} to inspect admitted inputs and commitments. Child results are not accepted from the browser. Private studies do not automatically publish manual SIMULATION_STUDY records or trigger the manual study reporting path.

Only one admitted Research child job is active per organization; other protocols wait. The worker rechecks coverage, lease fencing, membership, cancellation, deadline and policy before accepting output. Cancellation stops further authorized commits, while already committed historical artifacts remain retained. A terminal parent cannot acquire new Research artifacts.

Compute accounting conservatively charges declared paths × modeled steps × five variants for a newly started fence, including interrupted computation. Recovering an already committed receipt does not add a charge. These are authorized compute units, rather than measured CPU billing.

Interpret the report#

Read the saved report only when the current run advertises result availability. The comparison shows every admitted trial, compatibility reasons, outcomes, constraint failures and eligible within-scenario rankings.

Rankings compare capital-plan variants within each scenario. They do not rank stress scenarios against one another. An unavailable baseline blocks comparative ranking; failed, incompatible or ineligible outcomes remain visible. A fallback generated by the engine is not automatically an eligible recommendation. A model cannot hide mandatory limitations or replace deterministic rankings with its own calculations.

Result commitments bind saved inputs and artifacts. They do not independently reproduce the engine's numeric output. A completed result describes this exact hypothetical experiment and its coverage, rather than financial assurance.

Capability acknowledgements#

The planning confirmation requires explicit review of these twelve limitations:

1. Modeled steps are not calendar days.
2. Current data is not a historical as-of replay.
3. The CURRENT plan is planner-generated, rather than actual holdings.
4. Unlocks are aggregated at a modeled midpoint, without exact timing.
5. Positive buyer price impact is not modeled.
6. Modeled gas increases are limited to at most two times.
7. Quote identity and decimals are not verified by this planning contract.
8. Scenarios are hypotheses, rather than forecasts.
9. Unlock magnitude is a weighted participation proxy.
10. Historical returns use a fixed-return model replay.
11. Driver attribution is approximate.
12. Reserve/oracle breach is a composite modeled event.

Additionally, percentile differences are marginal comparisons, not percentiles of paired differences. A capital plan's apparent modeled advantage does not establish superiority at equal required capital. Inspect required capital and reserves alongside the objective value.

Generation and artifact size limits can make a trial fail or become ineligible for comparison. Oversized exact numeric outcomes are not rounded or clamped into an apparently safe result. Reopening a saved report does not update its source or assumptions; a changed decision requires a newly reviewed run.