6.10 ParameterChangeAuditor

1. Bot Identity

2. Purpose

ParameterChangeAuditor intercepts every config edit across the Polytraders fleet, records what changed, who changed it, when, and the before/after values with replay-grade detail.

3. Why This Bot Matters

• Parameter change not recorded

  Incidents cannot be root-caused; audit trails are incomplete for compliance.

• P0 parameter changed without alert

  A high-risk config change may go unnoticed until it causes a trading incident.

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

{ "retain_history_days": 365 }

if p.retain_history_days < 90: emit('AUDIT_RETENTION_WARN')

{ "alert_on_p0_change": true }

if param.tier == 'P0': alerting.emit('P0_PARAMETER_CHANGED')

8. Default Configuration

{
  "bot_id": "gov.parameterchangeauditor",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "retain_history_days": 365,
    "require_ticket_for": [
      "P0",
      "P1"
    ],
    "publish_to_audit_log": true,
    "alert_on_p0_change": true
  }
}

9. Implementation Flow

1. Hook into the config store write path of every bot; intercept before-write events.
2. Compute diff between old and new parameter values.
3. Record: bot_slug, param_name, old_value, new_value, editor_id, environment, timestamp, ticket_ref.
4. If param tier is in require_ticket_for and ticket_ref is absent, reject the change and emit AUDIT_TICKET_REQUIRED.
5. If alert_on_p0_change and param tier is P0, emit P0_PARAMETER_CHANGED alert immediately.
6. Emit OperationsReport(event_type=PARAM_CHANGED) to audit log.
7. Enforce retain_history_days; purge records older than retention window.

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.

// ---- PRE-WRITE HOOK ----
FUNCTION onConfigWrite(botSlug, paramName, oldVal, newVal, editorId, ticketRef):
  tier = paramTierMap.get(botSlug + '.' + paramName, 'P2')
  IF tier IN config.require_ticket_for AND ticketRef IS NULL:
    EMIT OperationsReport(event_type='AUDIT_TICKET_REQUIRED',
      audited_bot=botSlug, param_name=paramName)
    RAISE ConfigError('AUDIT_TICKET_REQUIRED')
  record = {
    audited_bot: botSlug, param_name: paramName,
    old_value: oldVal, new_value: newVal,
    editor_id: editorId, ticket_ref: ticketRef,
    param_tier: tier, changed_at: now()
  }
  IF auditLog.available():
    postgres.insert('param_change_audit', record)
  ELSE:
    memBuffer.append(record)
    alerting.emit('AUDIT_LOG_UNAVAILABLE')
  IF tier == 'P0' AND config.alert_on_p0_change:
    alerting.emit('P0_PARAMETER_CHANGED', record)
  EMIT OperationsReport(event_type='PARAM_CHANGED', ...record)

// ---- RETENTION PURGE (scheduled) ----
FUNCTION purgeOldRecords():
  cutoff = now() - days(config.retain_history_days)
  postgres.deleteWhere('param_change_audit', changed_at < cutoff)

SDK calls used

• postgres.insert('param_change_audit', record)
• postgres.deleteWhere('param_change_audit', cutoff)
• alerting.emit('P0_PARAMETER_CHANGED', record)

Complexity: O(1) per config write; O(N) for retention purge where N = records older than cutoff

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Config write event",
  "source": "internal.config_store",
  "payload": {
    "bot_slug": "risk.liquidityguard",
    "param_name": "max_position_pusd",
    "old_value": 5000,
    "new_value": 7500,
    "editor_id": "alice@polytraders",
    "ticket_ref": "PTRD-1042"
  }
}

Output — what the bot emits

{
  "label": "OperationsReport — PARAM_CHANGED",
  "payload": {
    "report_id": "ops_paramchange_01HX9Z",
    "event_type": "PARAM_CHANGED",
    "audited_bot": "risk.liquidityguard",
    "param_name": "max_position_pusd",
    "old_value": 5000,
    "new_value": 7500,
    "report_kind": "OperationsReport"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OperationsReport object. See OperationsReport schema.

{
  "report_id": "ops_paramchangeauditor_01HX9Z",
  "bot_id": "gov.parameterchangeauditor",
  "event_type": "PARAM_CHANGED",
  "audited_bot": "risk.liquidityguard",
  "param_name": "max_position_pusd",
  "old_value": 5000,
  "new_value": 7500,
  "editor_id": "alice@polytraders",
  "ticket_ref": "PTRD-1042",
  "param_tier": "P1",
  "changed_at": "2026-05-09T10:00:00Z",
  "report_kind": "OperationsReport",
  "topic": "polytraders.reports.operations"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "gov.parameterchangeauditor",
  "event_type": "AUDIT_HOOK_FIRED",
  "audited_bot": "risk.liquidityguard",
  "param_name": "max_position_pusd",
  "diff": {
    "old": 5000,
    "new": 7500
  }
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, flush memory buffer to Postgres; no in-memory state required.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Direct database write to bypass the audit hook
• Providing a fake ticket reference for a P0 change

Mitigations

• Config store enforces hook invocation; direct DB writes are blocked by access controls
• Ticket references are validated against the change management system

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

ParameterChangeAuditor incidents are usually audit log unavailability or P0 parameter alerts.

On-call actions

Manual overrides

• —

Healthcheck

/internal/health/parameterchangeauditor → green if Postgres reachable; buffer_size == 0; last change recorded < 1h ago; red if buffer_size > 100 or Postgres unreachable

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%