Monitoring

Quick summary

Watch entitlement denials, replay attempts, usage, audit checks, outbox, and uncertain refunds. The current repository describes API/DB signals, not a shipped monitoring dashboard.

Use the indicators below to triage a symptom, confirm its source and time range, and open a recovery investigation when evidence is incomplete.

What to watch and where it lives. There is no shipped dashboard for these signals — they are API/DB surfaces plus cron behavior.

Security events (security_events)

GET /api/v1/security-events[?lic_id=] — seller-scope, tenant-scoped, Worker-only. Written by the PoP guard on every denial (license_blocked, replay/jti reuse, jkt mismatch, product drift) — with no keys, tokens, or PII in detail_json by contract.

Watch for: denial spikes per lic_id (sharing/replay probing), license_blocked bursts from one device, jkt anomalies after re-activation. Also reachable via gateway tool yetdapay_security_events and the yetdapay-license skill.

Usage & counters

• GET /api/v1/usage-counters[?lic_id=] — durable counters (tenant scope).
• GET /api/v1/licenses/:id/usage — per-license execution log + counters.
• Boundary: license_usage rows come only from DevPay-hosted /licenses/execute — BYOS executions are structurally invisible (limitations §3.5).

Audit chain & ledger integrity

• audit_events rows are integrity-hash chained (actor, actor_role, action, entity, entity_id, detail_json, retention_class, legal_hold, integrity_hash).
• GET /api/v1/audit/verify and GET /api/v1/ledger/verify (admin) — recompute the chains; a divergence is an incident.
• GET /api/v1/admin/audit (admin) — audit browsing.

Outbox & cron

• outbox statuses: pending / claimed (lease) / delivered / dead_letter. */5 cron dispatch is verified locally; a dead-letter build-up means the sink is down or OUTBOX_SINK_URL unset (delivery is consumer:none without it — expected in test envs).
• Stale claims (>lease) are auto-recovered by reconciliation's failed_or_stuck_outbox check — see Reconciliation.

Health & metrics

• GET /api/v1/health → {ok, request_id} — ok reflects the D1 binding; public.
• GET /api/v1/metrics → {ok, request_id, metrics} — admin only.
• GET /api/v1/admin/overview — platform operator summary.

Refund attempts

GET /orders/:id/refund-attempts (seller-owner) — any attempt stuck in needs_review is a manual-ops item; there is no sweeper (limitations §4.15).