6.16 ExposureExplainer

1. Bot Identity

Operational profile

2. Purpose

Produces a plain-English narrative of current portfolio exposure: which markets, which outcomes, how much pUSD is at risk, why each position was opened (linked back to the originating strategy and OrderIntent). Read by the Admin UI, the daily ops digest, and any incident review.

3. Why This Bot Matters

• Opaque positions

  A page of raw outcome IDs and notionals does not tell anyone whether the portfolio is balanced, concentrated, or running through resolution.

• Audit trail

  When something goes wrong, the first question is always 'why was that position open?' — without ExposureExplainer, the answer requires correlating five logs by hand.

• Daily review fatigue

  A narrative rendering compresses 200 line items into the 5 things a reviewer actually needs to read.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "digest_cadence_minutes": 60 }

schedule.every(p.digest_cadence_minutes).do(emit_narrative);

{ "concentration_warn_pct": 25 }

if (mkt.exposure_pct > p.concentration_warn_pct) flag(mkt);

8. Default Configuration

{
  "digest_cadence_minutes": 60,
  "concentration_warn_pct": 25
}

9. Implementation Flow

— not yet authored —

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

positions = portfolio.snapshot()
rows = [(p.strategy_id, p.market_id, p.outcome_id, p.size_usd) for p in positions]
rows.sort(key=lambda r: -r[3])
for r in rows:
  narrative.append(render_row(r))
  if exposure_pct(r) > p.concentration_warn_pct: flags.append(r.market_id)
emit('ExposureNarrative', narrative, flags)

11. Wire Examples

Input — what arrives on the wire

{
  "snapshot_ts_ms": 1715260000000,
  "positions": [
    {
      "strategy_id": "event_drift",
      "market_id": "0xabc",
      "outcome_id": "YES",
      "size_usd": 1200
    }
  ]
}

Output — what the bot emits

{
  "kind": "ExposureNarrative",
  "summary_markdown": "## Exposure as of 14:00 UTC\n- Strategy 'event_drift' is long $1,200 on YES in market 0xabc.\n",
  "concentration_flags": []
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "kind": "ExposureNarrative",
  "summary_markdown": "## Exposure as of 14:00 UTC\n- Strategy 'event_drift' is long $1,200 on YES in market 0xabc (Trump Q1 announcement); concentration 18%.\n- Strategy 'late_unwind' is short $400 on NO in market 0xdef.\n",
  "concentration_flags": []
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Dashboards

• 6.16 overview dashboard

16. Developer Reporting

"Per emission: digest_id, ts_ms, position_count, total_exposure_usd, flagged_markets."

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Last successful narrative cached for fallback emission.

State stores

Cold-start recovery

Cold-start hydrates from fast KV; missing keys default to safe fallback.

On restart

All in-flight decisions are re-evaluated; no bot decision is trusted across restart without re-emit.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Requires (graph.requires)

exec.order_lifecycle_manager

23. Security Surfaces

Read-only on portfolio + history. Emits to internal ops feed only.

Signing surface

None — bot does not sign or submit.

Mitigations

• Rate-limit per source
• Audit-log every override
• Require role-based authz on admin paths

24. Polymarket V2 Compatibility

25. Versioning & Migration

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

If narratives stop emitting: check the digest scheduler heartbeat in monitoring.

On-call actions

Manual overrides

• polytraders bot pause 6.16 — Disables the bot's enforcement layer; downstream consumers fall back to safe defaults.

Healthcheck

GET /healthz/exposure_explainer → 200 if last successful evaluation < 60s ago.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%