1.16 ManualOverrideAuditor

1. Bot Identity

Operational profile

2. Purpose

ManualOverrideAuditor intercepts every request to bypass or adjust a guardrail, enforces a rate limit on overrides per time window, requires a non-empty justification string, and emits an immutable RiskVote audit record for every approved or rejected override attempt. It ensures that manual guardrail bypasses cannot occur silently and that every override is visible to the risk team.

3. Why This Bot Matters

• Silent override of a guardrail

  Without audit enforcement, a guardrail can be bypassed without trace, removing the protective layer without any record for post-hoc review.

• Override rate limit bypassed

  Repeated overrides in a short window can be used to trade in conditions that guardrails are designed to block, effectively disabling the risk controls.

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

{ "max_overrides_per_window": 3 }

if (overrideCount >= params.max_overrides_per_window) return reject('OVERRIDE_AUDITOR_RATE_EXCEEDED');

{ "override_window_minutes": 60 }

const windowStart = now_ms() - params.override_window_minutes * 60000;

{ "require_justification": true }

if (params.require_justification && !override.justification.trim()) return reject('OVERRIDE_AUDITOR_NO_JUSTIFICATION');

8. Default Configuration

{
  "bot_id": "risk.manual_override_auditor",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_overrides_per_window": 3,
    "override_window_minutes": 60,
    "require_justification": true
  },
  "locked": {
    "require_justification": {
      "immutable": true
    },
    "max_overrides_per_window": {
      "min": 1
    }
  }
}

9. Implementation Flow

1. Receive override request payload: target_guardrail, requestor_id, justification, timestamp_ms.
2. Check KillSwitch; if active, REJECT all overrides immediately.
3. If require_justification=true and justification is empty, HARD_REJECT(OVERRIDE_AUDITOR_NO_JUSTIFICATION).
4. Load override count for requestor_id within the last override_window_minutes from Redis.
5. If override_count >= max_overrides_per_window, HARD_REJECT(OVERRIDE_AUDITOR_RATE_EXCEEDED).
6. If override_count == max_overrides_per_window - 1, attach WARN(OVERRIDE_AUDITOR_RATE_APPROACHING).
7. Emit immutable audit RiskVote with requestor_id, target_guardrail, justification, and timestamp.
8. Increment override counter for requestor_id in Redis (with window_minutes TTL).
9. Return APPROVE to allow the override to proceed.

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.

FUNCTION evaluateOverride(request):
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT RiskVote(HARD_REJECT, KILL_SWITCH_ACTIVE); RETURN

  IF params.require_justification AND NOT request.justification.strip():
    EMIT RiskVote(HARD_REJECT, OVERRIDE_AUDITOR_NO_JUSTIFICATION); RETURN

  windowStart = now_ms() - params.override_window_minutes * 60000
  counter = FETCH redis.zcount(request.requestor_id, windowStart, now_ms())
  IF counter IS NULL:
    EMIT RiskVote(HARD_REJECT, OVERRIDE_AUDITOR_DATA_UNAVAILABLE); RETURN

  IF counter >= params.max_overrides_per_window:
    EMIT RiskVote(HARD_REJECT, OVERRIDE_AUDITOR_RATE_EXCEEDED); RETURN

  IF counter == params.max_overrides_per_window - 1:
    annotations.append(WARN(OVERRIDE_AUDITOR_RATE_APPROACHING))

  // Write audit record atomically before approving
  ok = WRITE redis.xadd('audit_overrides', {
    requestor_id: request.requestor_id,
    target_guardrail: request.target_guardrail,
    justification: request.justification,
    timestamp_ms: now_ms()
  })
  IF NOT ok:
    EMIT RiskVote(HARD_REJECT, OVERRIDE_AUDITOR_DATA_UNAVAILABLE); RETURN

  redis.zadd(request.requestor_id, now_ms(), now_ms())
  EMIT RiskVote(APPROVE, audit_id=ok.entry_id)

SDK calls used

• redis.zcount(requestor_id, windowStart, now)
• redis.xadd('audit_overrides', record)
• redis.zadd(requestor_id, score, member)
• internal.killswitch.status()

Complexity: O(1) — constant Redis ops

11. Wire Examples

Input — what arrives on the wire

Override request — rate limit exceeded — internal

{
  "override_request_id": "ovr_b8c9d0e1f2a30008",
  "requestor_id": "ops_user_001",
  "target_guardrail": "risk.liquidity_guard",
  "justification": "Incident response — book feed down",
  "timestamp_ms": 1746800000000
}

Output — what the bot emits

RiskVote — HARD_REJECT rate exceeded

{
  "guard_id": "risk.manual_override_auditor",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "OVERRIDE_AUDITOR_RATE_EXCEEDED",
  "message": "ops_user_001 has submitted 3 overrides in the last 60 minutes.",
  "constraints": {},
  "checked_at": "2026-05-10T15:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.manual_override_auditor",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "OVERRIDE_AUDITOR_RATE_EXCEEDED",
  "message": "Requestor ops_user_001 has submitted 3 overrides in the last 60 minutes, exceeding the limit.",
  "constraints": {},
  "inputs_used": [
    "internal.override_counter",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-10T15:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "risk.manual_override_auditor",
  "decision": "HARD_REJECT",
  "reason_code": "OVERRIDE_AUDITOR_RATE_EXCEEDED",
  "inputs_used": [
    "internal.override_counter"
  ],
  "metrics": {
    "requestor_id": "ops_user_001",
    "target_guardrail": "risk.liquidity_guard",
    "override_count_in_window": 3,
    "max_overrides_per_window": 3,
    "window_minutes": 60
  },
  "checked_at": "2026-05-10T15:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Counter rebuilt from audit stream on cold start. If Redis unavailable, HARD_REJECT until restored.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Rotating requestor_id to bypass per-requestor rate limit
• Submitting overrides with boilerplate justification strings to pass the non-empty check without meaningful documentation

Mitigations

• Requestor ID is sourced from authenticated session token; cannot be spoofed by the requester
• Justification minimum length and keyword checks planned for v2 of this spec

24. Polymarket V2 Compatibility

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

ManualOverrideAuditor incidents typically involve a Redis failure causing fail-closed rejections, or a legitimate rate-limit breach requiring escalation to risk pod lead for review.

On-call actions

Manual overrides

• polytraders risk reset-override-counter --requestor-id <id> — After a confirmed legitimate incident response where the rate limit was exceeded; requires risk pod lead written approval.

Healthcheck

GET /internal/health/manualoverrideauditor → green: Redis reachable, audit stream writable, override counter TTL active; red: Redis unreachable, audit stream write failure, or counter TTL expired

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%