Trade Report

1. Lifecycle groups

Reporting is sequential. Bots are grouped by lifecycle stage — not by system layer — because a single trade walks through these six stages in order. Each group emits one canonical report kind.

2. ReportEnvelope schema

Every report — regardless of kind — wraps a kind-specific payload in this envelope. Identity, timing, outcome, evidence, dependencies, and retention policy are uniform across all six kinds. This is what makes cross-kind queries possible.

{
  "schema_version": "1.0.0",
  "report_id":      "rpt_<bot_slug>_<ulid>",
  "report_kind":    "ObservationReport | RiskVote | DecisionReport |
                     ExecutionReport | SettlementReport | OperationsReport",
  "supersedes":     null,                     // report_id of prior version, if correction
  "bot": {
    "bot_id":       "1.3",
    "slug":         "oracleriskmonitor",
    "version":      "2.1.3",
    "spec_version": "2.0.0"
  },
  "subject": {
    "trace_id":     "tr_01HX9...",            // shared across every report for one trade
    "intent_id":    "oi_01HX9...",            // null on OperationsReport
    "fill_id":      null,                     // populated only on ExecutionReport / SettlementReport
    "market_id":    "0xabcdef...",            // 32-byte hex (V2)
    "epoch":        "2026-05-09T14:00Z/15:00Z" // hourly bucket for time-window queries
  },
  "timing": {
    "observed_at":  "2026-05-09T14:32:01.234Z",
    "emitted_at":   "2026-05-09T14:32:01.241Z",
    "latency_ms":   7
  },
  "outcome": {
    "verdict":      "pass | reshape | reject | informational",
    "reason_code":  "LIQUIDITY_OK | ORACLE_DISPUTE_ACTIVE | ...",
    "severity":     "INFO | WARN | RESHAPE | HARD_REJECT | EXPLAIN"
  },
  "payload":        { /* report-kind-specific body, see below */ },
  "evidence": [
    { "kind": "polymarket.gamma.market", "url": "...", "snapshot_hash": "0x..." },
    { "kind": "onchain.tx",              "tx":  "0xf00...", "block": 64512345 }
  ],
  "depends_on_reports": [
    "rpt_marketscanner_01HX...",            // upstream reports that informed this one
    "rpt_liquidityguard_01HX..."
  ],
  "policy": {
    "user_visible":      true,
    "redacted_fields":   [],
    "retention_days":    2555,                // 7 years for SettlementReport
    "compliance_export": true                 // included in regulator bundle
  },
  "mode": "live"                              // live | shadow | paper | replay
}

Per-kind payload sketches

The envelope is uniform; the payload is not. Each kind has its own shape:

{
  "snapshot": {
    "best_bid": 0.62, "best_ask": 0.64,
    "depth_pUSD": { "bid_5pct": 42000, "ask_5pct": 38500 },
    "last_50_trades_lean": "+0.13"
  },
  "freshness_ms": 240,
  "source_api": "clob_public"
}

{
  "vote": "reshape",
  "original_size_pUSD": 1500,
  "new_size_pUSD": 820,
  "reasons": ["PORTFOLIO_GUARD_CONCENTRATION_LIMIT"],
  "explanation": "single-market exposure would breach 8% cap"
}

{
  "intent_emitted": true,
  "intent_id": "oi_01HX9...",
  "edge_bps": 14.2,
  "votes_received": [
    {"bot": "liquidityguard",  "vote": "pass"},
    {"bot": "portfolioguard",  "vote": "reshape", "size": 820}
  ],
  "shaped_intent_size_pUSD": 820
}

{
  "route": "clob_v2",
  "maker_or_taker": "maker",
  "fills": [{"price": 0.624, "size": 740, "tx": "0xf00...ba1"}],
  "fee_pUSD": 8.32,
  "builder_code": "0x...32bytes",
  "builder_fee_pUSD": 0.74,
  "latency_ms": 38,
  "slippage_bps_vs_mid": -0.4
}

{
  "fill_id": "fill_01HX9...",
  "tx": "0xf00...ba1",
  "gross_pnl_pUSD": 12.40,
  "fee_pUSD": -1.80,
  "rebate_accrued_pUSD": 0.45,
  "position_delta": { "0xabc...": +740 },
  "settled_at": "2026-05-09T14:32:01.880Z"
}

{
  "scope": "system | bot | experiment | budget",
  "metrics": { "bots_green": 96, "bots_red": 1 },
  "incidents": [],
  "period": { "from": "2026-05-09T00:00Z", "to": "2026-05-09T23:59Z" }
}

3. End-to-end example trace

Eleven reports, one trade, one trace_id. This is what the timeline viewer shows when you load /internal/trades/<trace_id>.

1. 14:32:01.001Pre-trade intelmarketscannerObservationReportinformationalTop-of-book snapshot taken, depth ±5% = $42k, no toxic flow detected.
2. 14:32:01.012Pre-trade inteloraclewatcherObservationReportinformationalUMA queue clean, no proposals or disputes within 24h.
3. 14:32:01.045Strategy decisionsum-to-one-arbDecisionReportinformationalEdge = 14.2 bps on outcome A. Proposed size $1,500 pUSD.
4. 14:32:01.058Risk & complianceliquidityguardRiskVotepassDepth headroom 3.2x — comfortably within limit.
5. 14:32:01.062Risk & complianceoracleriskmonitorRiskVotepassNo active proposal or dispute on this market.
6. 14:32:01.068Risk & complianceportfolioguardRiskVotereshapeConcentration cap 8% would breach at $1,500 → reshape to $820.
7. 14:32:01.071Risk & compliancecontractaddressguardRiskVotepassTarget contract on V2 allow-list, EIP-712 domain v2 confirmed.
8. 14:32:01.078Strategy decisionsum-to-one-arbDecisionReportinformationalAll votes collected, intent reshaped to $820, emitted to exec.
9. 14:32:01.116ExecutionsmartrouterExecutionReportpassPosted as maker @ 0.624, filled 740/740 in 38ms, builder code attached.
10. 14:32:01.880Post-tradepnl-reporterSettlementReportinformationalFill settled. Gross +$12.40, fee -$1.80, rebate accrued $0.45.
11. 14:32:02.030Governance & auditbuilderattributionOperationsReportinformationalBuilder fee $0.74 attributed to source bot sum-to-one-arb.

4. Reporting principles

1. Every bot reports — even read-only ones. — An Intelligence bot that observes but never votes still emits an ObservationReport per polled signal. If it produces no report, it cannot be audited.
2. Reports are immutable, append-only. — Once emitted to the report bus (Kafka topic polytraders.reports.<kind>), a report is never updated. Corrections emit a new report with supersedes referencing the prior report_id.
3. One trace_id per OrderIntent — across every stage. — All reports for a single trade share a trace_id. This is how the post-trade walkthrough joins 11 separate reports back into one story.
4. Reports cite their evidence. — Every report includes an evidence array — URLs, snapshot hashes, on-chain tx refs. A regulator should be able to replay the decision from the report alone.
5. Reports separate verdict from reason. — A RiskVote of reshape with reason code PORTFOLIO_GUARD_CONCENTRATION_LIMIT is human-readable; the verdict and the reason are independent fields. See reason-codes.
6. Reports declare their dependencies. — depends_on_reports chains a report back to the upstream reports that informed it. The DecisionReport from a strategy bot lists the RiskVote IDs from each guardrail it consulted.
7. User-visible reports are explicitly flagged. — policy.user_visible: true means the report is shown in the user-facing trade history. Most reports are internal-only.

5. Routing matrix — producers × consumers × topic × retention

One Kafka topic per report kind. Partition keys are chosen so that all reports for one trade land on one partition (trace_id) — except observation polls (sharded by market) and operations rollups (sharded by bot+epoch).

6. SLOs per report kind

Reporting itself is a service — and it has its own SLOs. Miss any of these and a page fires.

7. Reasoned alerts — patterns over reports

Alerts derived from report streams, not from raw metrics. Each pattern explains itself.

8. Cross-report join keys

The join surface that lets you reconstruct any trade or any time window.

9. User-visible vs. internal

Most reports are internal-only. The user trade history is built from a strict subset.

10. Replay modes

Every report carries a mode field. This is how shadow runs, paper trading, and historical replays stay separable from live books.

11. Bus failure mode

If the report bus is down, what each kind does is different. RiskVote and DecisionReport fail-closed (block the pipeline). Settlement buffers to disk. Observation drops.

12. Per-bot reporting checklist

Every bot's reporting block must declare the following — promotion gate to BETA blocks until all eight are present.

• Bot declares which report kind(s) it emits.
• Bot declares the topic(s) it publishes to.
• Bot declares emission cadence (every-event, every-N, every-period).
• Bot declares its payload schema (one of the six payload sketches, or a documented extension).
• Bot declares retention class (matches policy.retention_days for the kind).
• Bot declares user-visibility default + redaction list.
• Bot declares behaviour when the report bus is unavailable.
• Bot declares which upstream report kinds it consumes (depends_on_reports populator).

13. Sampling rules

High-volume kinds may sample. Audit-critical kinds (RiskVote, DecisionReport, ExecutionReport, SettlementReport) never sample.

14. Schema evolution rules

1. Additive only — never remove or rename fields. Deprecated fields stay until a major version bump.
2. schema_version uses semver. MAJOR = breaking, MINOR = additive, PATCH = doc-only.
3. Producers stamp the schema_version they emit. Consumers tolerate any MINOR/PATCH bump within their declared MAJOR.
4. Unknown fields MUST be preserved on round-trip. Consumers ignore but never strip.
5. Deprecation window: a field marked deprecated lives ≥ 90 days before removal in the next MAJOR.
6. Breaking changes go through the principles → V2-migration playbook (see v2-migration).

15. Compliance / regulator export

The bundle a regulator receives. Daily incrementals + quarterly full archive. PII stripped per envelope policy.

Trade timeline viewer (UX sketch)

The internal tool that joins all reports for one trace_id into a single screen. URL pattern: /internal/trades/<trace_id>.

Panels

1. Header — trace_id, intent_id, market title, total elapsed time, final outcome (filled / blocked / cancelled)
2. Timeline — Vertical bar chart, 1 row per report, sorted by emitted_at, coloured by stage
3. Report inspector — Click any bar → JSON envelope panel with collapsible payload + evidence
4. Dependency graph — Force-directed graph of depends_on_reports edges for this trace_id
5. Diff vs. shadow — If a paired shadow run exists, side-by-side diff of verdicts and fills
6. Replay button — Re-runs this trace against current code in replay mode, opens new viewer with replay_run_id

Keyboard shortcuts

• / — search by trace_id, intent_id, fill_id, market_id
• j / k — jump to next / previous report in timeline
• v — toggle verdict-only filter
• e — open evidence panel

Cross-report dependency graph

Which kinds inform which. The DecisionReport reads ObservationReports + RiskVotes. The SettlementReport reads ExecutionReports. Operations rolls up everything.