Operations, reconciliation, and rollback

Polyflight separates game outcome from wallet delivery. A ticket can be definitively won or cancelled while its payout or refund remains owed. Never change the public result to hide a wallet failure.

Evidence chain

For every money case, trace the same immutable business effect across:

1. purchase request or ticket;
2. wallet balance operation, stable idempotency_key, and immutable walletTransport;
3. operator wallet ledger evidence and optional remote_reference;
4. payment obligation, when money is owed;
5. webhook event_id and delivery attempts;
6. native-IDR accounting event and confirmed cash clearing;
7. current reporting/liabilities or finalized statement and export.

Use the dashboard's Polyflight → Tickets, Balance operations, Settlement reports, and webhook delivery views. Use API Playground for the same scoped GET resources. An operator can inspect its own evidence but cannot mark a wallet mutation applied or change commercial terms.

Normal state interpretation

• Purchase pending: the durable intent exists; do not submit another purchase merely because execution is still running.
• Purchase compensated: the debit applied but no ticket was admitted, and the exact reversal completed.
• Won / payout pending: result is final; user credit remains an outstanding liability.
• Cancelled / refund pending: cancellation is final; full original debit remains an outstanding liability.
• Paid / refunded: wallet evidence confirms the corresponding credit.
• Manual review: remote cash state is ambiguous or requires authenticated evidence; it is not success or failure by assumption.

Reconciliation procedure

1. Freeze automated or human replay for the affected effect.
2. Capture operator, external user, purchase/ticket/flight IDs, operation ID, pinned walletTransport, stable idempotency key, UTC window, request trace IDs, and webhook event IDs.
3. Query the matching simulator or REST v1 ledger by the financial idempotency key, not only by X-Polynion-Request-Id.
4. Compare transport, user, currency, amount, reason, and material metadata with OpenPoly's immutable request evidence. Do not move recovery to a different transport.
5. Determine one authoritative outcome: applied, not applied, or still unknown.
6. Provide authenticated ledger evidence/reference to Polynion operations. Operator dashboard/API access cannot self-resolve a money effect.
7. An authorized Polynion administrator records confirmed_applied or confirmed_not_applied with a required reason, evidence reference, and expected state version. authorized_original_key_resume is reserved for definitive non-application when the operator's same-key behavior permits safe resumption.
8. Verify the resulting business transition, liability, webhook, statement activity, and user balance. Conflicting or duplicate decisions must not create another ticket or money movement.

If non-application is definitive, resuming the original operation is allowed only when the operator's idempotency behavior is known to permit it. Otherwise resolve the existing obligation with manually completed payment evidence. Never use a fresh key to bypass an uncertain effect.

Failure scenarios

Definite purchase debit rejection

Expected state: purchase failed, no ticket, no fee or position accounting, and no compensation operation because no money moved.

Debit applied, response timed out

Expected state: no automatic primary replay and no ticket until authoritative evidence confirms application. Once confirmed, OpenPoly records clearing exactly once and either admits the ticket if still valid or schedules exact compensation if admission is no longer possible.

Debit applied after gate closure

The gate wins over request start time. No late ticket is forced into the snapshot. OpenPoly reverses the full debit through mini_app_polyflight_purchase_compensation.

Admission response lost

Retry/query the same purchase intent. If admission committed, return the existing ticket. Do not reverse a debit simply because an internal response was lost.

Winning credit failed or timed out

The ticket remains won. The obligation remains owed or in manual review; the statement retains the winnings liability. Do not label it paid and do not change signed position income.

Cancellation refund failed or timed out

Fee entitlement ends at cancellation, not at wallet delivery. The exact full stake remains refund payable until confirmed. A refund and winning payout cannot coexist for the same ticket.

Duplicate delivery

The same key and parameters must return the original effective result. A different payload under the same key is a conflict and must not mutate money. Webhook delivery/replay may repeat an event envelope, so receivers deduplicate by event_id; it never authorizes a wallet mutation replay.

Missing or stale comparison rate

No FX lookup occurs during purchase, payout, or gate processing. If a flight was committed with a cached fallback rate, that frozen rate remains authoritative and is disclosed after reveal. If no valid observation existed before boarding, IDR entry is unavailable for that flight while first-party Credits participation and global progress continue.

Operator outage or suspension

Block new admission. Continue recovery for already-owed payout, refund, compensation, statement reads, and reconciliation. One operator outage must not withhold the global result or first-party notifications.

Required staging drills

Use dedicated, user-scoped simulator wallets to exercise:

• definite debit rejection;
• debit applied then timeout;
• credit applied then timeout;
• duplicate key with identical parameters;
• duplicate key with different parameters;
• admitted ticket cancellation and exact native refund;
• late confirmed debit and compensation;
• losing, winning/payout-pending, fully paid, and manual-review cases.

Launch the test user from Operator Dashboard Simulator → Users → Simulator with product polyflight and follow the real single-use launch URL into the Mini App Client. Do not inject a session cookie or replace this with API-only testing. Keep the operator's rest_v1 configuration unchanged; only dedicated simulator-tagged users use simulated wallets.

Simulator evidence proves OpenPoly's state machine, not a real operator adapter. Separately run the REST v1 contract/failure drills against dedicated non-production external-wallet infrastructure using small amounts and an explicit test user. Never use production credentials, production users, or production wallet money for staging certification.

Safe rollback and incident containment

The first containment action is to disable new Polyflight operator purchases. Keep payout, refund, compensation, reconciliation, webhook evidence, and report reads running.

Safe actions:

• disable operator Polyflight entry;
• pause future global generation when protocol integrity is in question;
• deploy a forward fix or the last build that can read and process v5;
• revert only future, unclaimed-wave protocol policy after accounting for existing flights;
• preserve operations, events, statements, proof artifacts, and audit history.

Unsafe actions:

• rolling back to a binary that cannot read v5 while v5 flights or obligations exist;
• dropping or reversing financial/proof tables as traffic rollback;
• changing a committed valuation, snapshot, result, winner, payout, or terms version;
• cancelling a post-commitment flight through normal operations;
• replaying an ambiguous primary mutation or inventing a new idempotency key;
• deleting evidence or rewriting a finalized statement;
• switching all operator users to simulator mode.

After containment, reconcile the oldest unresolved operations and liabilities, confirm webhook delivery, compare statement/export parity, and retain redacted evidence. Production deployment or operator enablement is a separate authorized change; staging readiness does not imply it.