# CS2 command recovery extension

Contract: `arena.cs2.recovery.v1`. This is additive to the pinned allocation and
event `arena.cs2.v1` kit in `../v1/`. It does not change those artifacts or enable
production requests. Arena requires this extension before enabling its dispatcher.

The original five provider operations remain. Add two **provider-side** routes:

| Method | Route | Effect |
| --- | --- | --- |
| GET | `/v1/requests/{request_id}` | Read the durable decision for that original command; never creates or starts anything. |
| POST | `/v1/requests/{request_id}/stop` | Record a durable stop decision if execution has not begun; otherwise return the actual pending/applied state. |

These are hosted by the CS2 provider, not hybrid-arena.com. The request ID is the
original lowercase 32-hex `request_id`. Keep all command IDs within the same
server-derived Arena authority namespace, including across signing-key rotation.
Verify the existing `ARENA-CS2-HMAC-V1` signature, exact method/path/body, clock,
nonce, key validity and scope before looking up a record. No browser cookies or
Identity tokens are accepted. Keys and key material must be unique across scopes.

## Exact command binding

`request_digest` is lowercase SHA-256 of these bytes:

```text
UPPERCASE_METHOD + "\n" + EXACT_ORIGINAL_PATH + "\n" + EXACT_ORIGINAL_BODY_BYTES
```

Do not parse and reserialize the original JSON before computing this digest.
A request ID reused with different bytes must return 409. Retain the original
response for an applied command; a later allocation status is not the historical
response to a particular start or roster command. An allocation ID is not a
substitute for a command receipt, especially after a lost create response.

The stop body contains exactly:

```json
{"schema":"arena.cs2.command-stop.v1","request_digest":"<64 lowercase hex>"}
```

GET has no body or query. A successful response is HTTP 200 JSON with exactly
`schema`, `provider_id`, `environment`, `request_id`, `request_digest`, `state`,
`result`, and `observed_at`. Schema is `arena.cs2.command-receipt.v1`; environment
is `staging` or `production`. `observed_at` is the current ISO UTC timestamp with
milliseconds (not the command's original execution time).

| State | Digest | Result | Meaning |
| --- | --- | --- | --- |
| `unknown` | null | null | No durable record; NOT proof that a delayed request cannot arrive. GET only. |
| `pending` | original digest | null | Registered or executing; no final outcome is known. |
| `applied` | original digest | original v1 Allocation response | Effect confirmed and immutable. May win a race with stop. |
| `canceled` | original digest | null | Durable guarantee that this exact command did not execute and can never execute later. |

A stop for an unknown request must insert a persistent tombstone. All original
create/roster/start/cancel paths must consult the same journal before an effect.
A stopped late original request cannot execute, even after process restart.
A stop for queued work must atomically fence the execution claim. If execution
has been claimed or its effect is uncertain, report `pending` until actual
provider/game reconciliation determines the outcome. Do not return `canceled`
merely because a timeout, 404, process exit, expired lease, or network error occurred.
`applied` remains applied; stopping a command is not undoing an allocation or game.
A separate allocation cancel operation is needed for an already-created resource.

No 404 or 503 is a terminal decision. Unsupported recovery routes must keep Arena
uncertain. Stop responses cannot say `unknown`. No automatic journal/tombstone
pruning is permitted while original commands could still be accepted.

## Reference implementation and tests

Install the original kit's pinned dependencies first:

```sh
npm ci --prefix ../v1
node --test test.mjs
```

`provider-journal.mjs` provides a real SQLite WAL/FULL journal with authority
isolation, queued/executing claims, persistent stop tombstones and encrypted
immutable allocation responses. Supply an owner-only database and a dedicated
32-byte storage key; preserve both over restart. Do not share it with Identity
or put it in source. The database is bound to one provider/environment.

Call `register(authority, requestId, digest)`, then `claim(...)` before the
provider effect. A false claim never authorizes another execution. When the
provider has durable evidence that the effect completed, call `applied(...)`
with the original v1 Allocation response. `lookup` and `stop` expose the extension.
Authority comes from verified service-key configuration, never a request body.

The helper does not launch CS2, authenticate Steam, reconcile a Docker/game
operation, or make an external side effect atomic with SQLite. Implement durable
idempotent allocation/game commands under the same request ID and reconcile an
`executing` record after a crash. Never blindly execute it again. A stopped
executing record remains pending in this helper until an applied result is known;
provider-specific proof of no effect needs its own correctly fenced reconciliation.

`verify-recovery.mjs` can check a reviewed staging service without allocating a
server. Use a mode0600 private JSON config with `provider_id`, `environment`
(`staging`), `origin`, `command_key_id`, and `command_key` (64 lowercase hex).
It writes one permanent stop tombstone for a fresh probe ID; no roster or game
is submitted. This explicit flag acknowledges that staging write:

```sh
node verify-recovery.mjs --staging-stop /absolute/private-config.json
```

Restart the provider and rerun with the returned `probe_request_id` as the last
argument to verify persistence. Never post the config or keys in a PR. This probe
is not real-game acceptance, authenticated Steam admission or a throughput test.

## Arena recovery behavior

Arena journals original bytes before send and persists uncertainty before I/O.
After a lost reply it first looks up the original request. Applied results are
recorded as facts even if the player has since withdrawn permission. Canceled
receipts release only the pending command lock; no credits or payments exist here.

For unknown work, a fresh valid consent check is required before resending the
original bytes. Known pending creates/cancels are polled while the bridge reconciles
them. Pending starts are retried with the exact original POST body/request ID, a
fresh signature nonce and fresh consent, only while dispatch is enabled. The
bridge may keep its active lease pending until a later retry; Arena retains
bounded backoff. Read-only recovery stays read-only. Withdrawn/expired consent requests
a durable stop instead of resending create/start. A stop that loses to an applied
operation records the applied outcome; it never invents a cancellation. A start
that already happened requires an explicit provider admission/removal policy.

The Core worker processes one command per invocation, persists 5–300 second
backoff, reloads private provider keys/controls before every outgoing request and
refuses a changed provider/environment/origin binding. New dispatch has a separate
`dispatch_enabled` gate. Recovery reads/stops and allocation cancellation can
continue when new dispatch is paused, using still-valid enabled provider keys.
The timer remains disabled until reviewed staging provisioning and acceptance.

## Joint acceptance still required

Return staging origin and provider/server IDs, exact builds, supported maps and
regions, and a secure key-provisioning reference in the existing draft PR. Verify
lost create/start/roster/cancel replies, stop-before-arrival, stop-after-claim,
provider/Arena restarts, key rotation/revocation, malformed or mismatched receipts,
withdrawn Steam permission and the actual admitted player's removal policy.
Then run the existing real-match/roster/event acceptance matrix. No production
CS2 enrollment, matches, markets or real-value execution is activated by this kit.


### Read-only restart verification

Run `node verify-recovery.mjs --staging-stop /absolute/private-config.json` once to create a probe.
After the operator confirms a provider restart with its database retained, run
`node verify-recovery.mjs --staging-restart /absolute/private-config.json ORIGINAL_PROBE_ID`.
This mode makes only signed GET requests and requires the original canceled record on both reads.
An unknown or pending record fails; no stop is recreated. Keep the restart time/revision reported by
the provider alongside the separately observed reads. The normal `--staging-stop` mode is a setup
and idempotency check, not proof that a record survived restart.
