Forge Pool

Appearance

Orchestration Adapter Example ​

Overview ​

This example shows a multi-stage orchestration adapter.

It coordinates multiple execution steps across primitives and shapes one higher-level result.

This is the standard pattern for advanced domain workflows in Forge.

When To Use This Pattern ​

Use this pattern when the adapter must:

  • coordinate multiple primitive calls
  • manage stage order
  • pass outputs between stages
  • combine results into a final surface

Typical examples:

  • institutional risk execution
  • perception pipelines
  • scenario discovery plus ranking
  • multi-stage domain chains

Lifecycle ​

text
Input → Validate → Transform → Plan → Execute Stage 1 → Execute Stage 2 → Aggregate → Finalize → Output

Example Use Case ​

A risk workflow needs to:

  1. run probabilistic portfolio stress using Monte Carlo
  2. run contagion analysis using graph propagation
  3. combine both into a scenario-level risk result

The adapter orchestrates the chain.

The primitives still perform the compute.

Example Flow ​

text
Normalized portfolio + selected scenarios
    ↓
risk-execute adapter
    ↓
mc@1 / finance.portfolio.v1
    ↓
graph@1 / financial.contagion.v1
    ↓
risk-execute adapter
    ↓
scenario risk output

Example Input ​

json
{
  "normalized_portfolio": {
    "portfolio_id": "PF-001",
    "as_of": "2026-04-05T12:00:00Z",
    "positions": [
      {
        "node_id": "AAPL",
        "asset_type": "equity",
        "exposure": {
          "market_value": 21050
        },
        "risk_traits": {
          "volatility_hint": 0.22
        }
      },
      {
        "node_id": "UST-10Y",
        "asset_type": "bond",
        "exposure": {
          "notional": 250000
        },
        "risk_traits": {
          "rate_sensitive": true
        }
      }
    ]
  },
  "scenario_exploration": {
    "selected_scenarios": [
      {
        "scenario_id": "stress-001",
        "signature": {
          "market_shock": -0.18,
          "rate_shock_bps": 220,
          "liquidity_stress": 0.35,
          "correlation_break": 0.28
        }
      }
    ]
  },
  "execution_policy": {
    "selection_mode": "top_n",
    "max_scenarios": 1,
    "mc_iterations": 1000000,
    "graph_steps": 5,
    "seed_strategy": "explicit_per_scenario"
  }
}

Stage 1 — Primitive Request Built for Monte Carlo ​

json
{
  "op": {
    "name": "mc",
    "version": 1,
    "profile": "finance.portfolio.v1"
  },
  "args": {
    "iterations": 1000000,
    "start_value": 271050,
    "drift": -0.04,
    "volatility": 0.31,
    "shock_prob": 0.19
  },
  "seed": {
    "mode": "explicit",
    "value": "PF-001-mc-stress-001"
  }
}

Stage 2 — Primitive Request Built for Graph ​

json
{
  "op": {
    "name": "graph",
    "version": 1,
    "profile": "financial.contagion.v1"
  },
  "args": {
    "steps": 5,
    "nodes": [
      { "id": "AAPL", "type": "equity" },
      { "id": "UST-10Y", "type": "bond" }
    ],
    "edges": [
      { "from": "AAPL", "to": "UST-10Y", "weight": 0.15, "type": "exposure" }
    ],
    "initial_state": {
      "stress": {
        "AAPL": 0.42,
        "UST-10Y": 0.31
      }
    }
  },
  "seed": {
    "mode": "explicit",
    "value": "PF-001-graph-stress-001"
  }
}

Example Final Output ​

json
{
  "adapter_name": "risk-execute",
  "adapter_version": "1.0.0",
  "risk_execution": {
    "portfolio_id": "PF-001",
    "profile_bundle": {
      "mc": "finance.portfolio.v1",
      "graph": "financial.contagion.v1"
    },
    "scenarios": [
      {
        "scenario_id": "stress-001",
        "mc_result": {
          "summary": {
            "mean": -0.07,
            "p95": -0.18,
            "p99": -0.26
          }
        },
        "graph_result": {
          "failure_prob": 0.41,
          "critical_nodes": ["AAPL"]
        }
      }
    ],
    "combined_summary": {
      "worst_loss_p99": -0.26,
      "highest_failure_prob": 0.41,
      "top_critical_nodes": ["AAPL"]
    }
  },
  "replay_refs": {
    "scenario_count": 1,
    "seed_strategy": "explicit_per_scenario"
  }
}

What the Adapter Actually Does ​

This adapter is responsible for:

  • validating normalized portfolio and scenario inputs
  • selecting scenarios
  • building stage-specific primitive requests
  • dispatching execution in the right order
  • passing results across stages
  • shaping the final domain result

This adapter is not responsible for:

  • Monte Carlo truth
  • graph truth
  • execution engine behavior
  • primitive semantics

Pseudocode ​

text
receive normalized portfolio and scenarios
validate input
select execution set
build MC request for scenario
execute MC primitive
build graph request using scenario + MC summary
execute graph primitive
combine results into scenario risk surface
return final domain output

Why This Pattern Matters ​

This is the core of advanced Forge usage.

It proves that:

  • adapters can coordinate complex workflows
  • primitives remain the canonical compute substrate
  • multi-stage systems can be built without fragmenting execution truth

Invariants Satisfied ​

This pattern preserves:

  • external compute truth
  • explicit stage boundaries
  • traceable primitive usage
  • honest output shaping
  • reproducible execution flow

Mental Model ​

The adapter coordinates the chain.

Forge remains the source of truth at every compute step.

Next ​