Orchestration Decision Readout

Orchestration Decision Readout is a compact, read-only explanation surface for how a workflow or candidate-search episode was assembled. It returns bounded decision rows, a top-level status, and optional derived advisory blocks that help you tell the difference between local row issues and a broader rollup gap.

This surface is for inspection, debugging, and integration. It does not choose an action, reroute execution, or grant provider authority by itself.

Live BMO TUI: a real provider-backed turn uses `get_orchestration_decision_readout` on bounded sample evidence, then explains the operator value of `aggregate_summary`, `recommendation_quality`, and `composite_rollup_blocked` without exposing raw prompts or provider payloads.

When to use it

Use the readout when you need to inspect orchestration evidence without reading internal traces or raw provider payloads.

Good moments to check it:

When a workflow result looks degraded and you need the row-level reason.
When candidate selection, pruning, merge, or handoff behavior needs a bounded explanation.
When an integration needs a stable JSON contract instead of TUI inspection.
When you want to distinguish between a blocked row and a missing composed rollup surface.

What it returns

Every response includes:

Field	Meaning
`schema_version`	Versioned readout contract.
`generated_at_unix`	UTC generation time as a Unix timestamp.
`status`	Overall posture derived from the rows and composed rollup availability.
`composite_rollup_available`	Whether the composed rollup surface was available when the readout was built.
`rows`	Bounded decision rows reconstructed from workflow, candidate-search, and explicit advisory evidence.
`warnings`	Optional bounded warning strings.

The response may also include two derived blocks:

Derived block	When it appears	What it means
`aggregate_summary`	When rows or warnings are present	Advisory rollup over row counts, warning counts, and composed rollup availability.
`recommendation_quality`	Only when recommendation rows exist	Descriptive metrics over recommendation evidence already present in the readout.

Provider recovery evidence remains conditional. When session-scoped owner evidence is available, the readout may include a provider_recovery_ref on a bounded row owned by provider_recovery. That row is advisory: it cites provider recovery posture without taking ownership of provider truth.

How to read `aggregate_summary`

aggregate_summary is derived. It does not override the row-level evidence.

Field	Meaning
`status`	Derived overall advisory posture.
`total_rows`	Number of bounded decision rows in the readout.
`warning_rows`	Row count carrying warning severity.
`blocks_rollup_rows`	Row count that blocks a composed rollup.
`blocks_promotion_rows`	Row count that blocks promotion.
`warning_count`	Count of top-level warning strings.
`composite_rollup_blocked`	Signals that the composed rollup surface itself was unavailable, even if no individual row is blocked.

The important distinction is this:

A row-level blocked state lives in rows.
A composed rollup gap lives in aggregate_summary.composite_rollup_blocked.

That lets you tell whether the problem is in one primitive row or in the absence of the higher-level rollup surface.

How to read `recommendation_quality`

recommendation_quality is descriptive, not authoritative. It summarizes only the recommendation rows already present in the payload.

Field	Meaning
`total_recommendations`	Total recommendation rows.
`actionable_recommendations`	Recommendation rows with a `next_action`.
`role_recommendations`	Recommendation rows carrying an advisory role.
`topology_recommendations`	Recommendation rows carrying an advisory topology.
`model_recommendations`	Recommendation rows carrying an advisory model.
`route_recommendations`	Recommendation rows carrying an advisory route.
`warning_recommendations`	Recommendation rows that also carry warning severity.

If no recommendation rows exist, this block is omitted.

Surfaces

The same contract is exposed through multiple surfaces:

Surface	Use
`POST /v1/orchestration-decision-readout`	HTTP read for integrations and tooling.
`get_orchestration_decision_readout`	Native agent read surface returning the same JSON contract when server-backed parity is enabled.
`bmo_get_orchestration_decision_readout`	MCP read surface returning the same JSON contract when app-backed MCP parity is enabled.
Runtime features	Discovery metadata advertises the parity route, the conditional `recommendation_quality` block, and conditional provider recovery references.

Request shape

The HTTP route accepts bounded reconstruction inputs. Native and MCP calls use the same shape, with one extra convenience: when session_id is omitted, a session-bound tool or MCP context may supply it implicitly.

Field	Meaning
`session_id`	Optional session identifier used to resolve owner-backed provider recovery references. For HTTP, pass it explicitly in the JSON body when you need session-scoped provider recovery evidence.
`run_id`	Optional run identifier for bounded handoff rows.
`workflow_id`	Optional workflow identifier for bounded handoff rows.
`workflow_nodes`	Optional workflow DAG evidence rows.
`candidate_search`	Optional candidate-search evidence for branch, score, prune, merge, and recommendation rows.
`additional_rows`	Optional explicit bounded decision rows.
`composite_rollup_available`	Whether the composed rollup surface is available for this readout.

What it does not expose

The readout is intentionally bounded:

No raw prompt text
No raw tool bodies
No provider payloads
No hidden chain-of-thought or private deliberation
No orchestration-owned provider health truth; provider recovery surfaces stay authoritative