# Raif's agent: build the CS2 provider integration

Contract: `arena.cs2.v1`, kit version `1.0.0`. Start with [README](./README.md), [provider OpenAPI](./provider.openapi.json), [Arena receiver OpenAPI](./arena.openapi.json) and [JSON schemas](./schemas.json). Download the [runnable kit](./arena-cs2-kit.tar.gz). The web copy and repository under `public/integrations/cs2/v1/` are the same contract.

## Decision already made

**Hybrid-ID owns identity/Steam linking → Arena owns consent, roster and match → Raif's service owns game allocation, authenticated admission and CS2 telemetry.** Do not implement another identity provider or require Hybrid-ID internal tokens. Arena's dedicated website already uses OIDC; the legacy-session finding applies to a separate client.

Arena's separate Steam permission flow and optional identity-private Explorer receipts have been deployed. Public receipts are not admission credentials and do not disclose Steam IDs. No further architecture handoff to Hybrid-ID is needed to start provider implementation. The first real consented roster and account acceptance remain part of activation.

## Work you can start now, in order

1. **Control service:** implement the five provider routes; durable request IDs, source bindings, stable allocation IDs and epochs; boot/ready/live/completed/canceled/failed status; private connection host/port; versioned pre-start roster replacement; expiry cleanup and capacity reservation. Keep match allocation and process lifecycle outside the game thread. Use a pinned CS2/Metamod/CounterStrikeSharp/plugin build and record their versions/config hashes.
2. **Authenticated admission:** use the game server's successful Steam authentication callback. Match the authenticated Steam ID to the private Arena roster, enforce team/slot, reject outsiders, and recheck reconnect/team switches. Keep stable teams independent of T/CT. Emit admitted-player events only after successful validation. Public player aliases come from Arena, not Steam names.
3. **Durable raw capture and normalized adapter:** retain the existing plugin capture leg if useful, but persist raw batches and normalized pending bytes. Implement the versioned event adapter and separate outbound signature. Do not use an in-memory queue as the only recovery source. Fail closed on loss; never treat a gap log message as clean continuity.
4. **Acceptance harness:** run `npm test`, `npm run verify` and `node demo.mjs` in this kit; then aim the provider checker at your disposable staging service. Supply exact source revision and test evidence. A real CS2 instance is needed for admission, halves/overtime, reconnect and final-result checks.
5. **Staging handover:** publish your implementation branch/commit and non-secret operating guide. Supply private staging origin, source provider/server identifiers, supported map/region, pinned versions and secure key-provisioning reference. Keys themselves go through the existing private operator channel, never repository/docs. Arena then provisions the live adapter and runs the joint acceptance match before activation.

You can complete steps 1–4 against localhost today. The kit deliberately removes dependence on production credentials while preserving the production boundaries. It does not provision a machine or authorize a server purchase. Existing capacity/cost estimates remain unvalidated until a real concurrent-match load test.

## Adapt the reviewed plugin rather than blindly forwarding it

Reviewed revision: `5650d3caa62c533fba217825b50de4eb22afc9b4` in <https://github.com/raifemre/cs2-server>.

| Existing raw field/behavior | Required adapter behavior |
| --- | --- |
| `server_id`, `boot_id` | Bind privately to allocated provider/server/match/epoch. Boot ID alone is not an authorized allocation |
| `batch_seq`, `prev_hash` | Verify the raw chain; keep its evidence privately. Create a separate normalized batch sequence/digest chain |
| Event `seq` starts at zero | Preserve raw cursor privately; normalized admitted stream starts at 1 and has stable IDs |
| `ts_ms`, nullable `tick` | Convert actual source observation to UTC milliseconds; require valid simulation timing for normalized gameplay; warmup/plugin-loading events are not match actions |
| Reflective `type` / `data` | Explicit allowlisted adapters for kills, health/armor damage, joins/leaves, round boundaries, sides, bomb actions and final stats; unknown plugin data stays private |
| Player snapshot Steam ID/name | Look up opaque Arena participant ID only after authenticated roster admission; strip raw identity before outbound batches |
| `dropped` count / queue overflow | Mark source integrity hold; attach raw missing-range evidence when known. Never silently acknowledge as a healthy game |
| Memory-only pending batch/boot state | Durable outbox before sending; recover exact bytes across process restart |
| Raw receiver acknowledges before callback persistence | Atomic event/cursor/receipt commit; callback completion must be awaited; same ID/different bytes conflicts |
| T/CT scores | Map onto stable team IDs through half and overtime swaps; verify final scores against the agreed rules |

The current plugin project has not been compiled or exercised against a real server in this Arena review. Its raw receiver's existing tests are useful, but do not establish roster enforcement or end-to-end production acceptance.

## Ownership and remaining activation work

| Owner | Deliverable | Current state |
| --- | --- | --- |
| Hybrid-ID | Identity, Steam linking, scoped consent, optional public receipt | Deployed; real new Arena Steam-consent acceptance still to record |
| Arena | Private consented Steam reads; partner docs and local contract kit | Deployed website flow; kit published with this handoff |
| Raif | Control API, real authenticated admission, durable plugin adapter, staging evidence | Implementation required beyond reviewed main |
| Arena | Persistent CS2 orchestration/binding, per-source key registry, private production receiver, public alias projection and match-room adapter | Production integration not deployed; implement against Raif's staging target and this contract |
| Joint | Consented real players, negative admission tests, full match/fault acceptance and load measurements | Not run |
| Arena | Two-team practice market/rulebook activation | Separate gate; existing four-house Star Quest market must not be reused blindly |

Nothing here enables real money, funding or Stripe. Do not claim a successful local demo means CS2 is live in Arena. A real match must be accepted before changing the manifest's production availability flags.

## Required end-to-end acceptance evidence

- Valid consented roster joins; outside/non-rostered Steam account denied; spoofed payload identity denied; unauthorized team change denied.
- Same authenticated player reconnects into the assigned slot. Bots are visibly distinct; no bot can satisfy a human authentication check.
- Start binds exact roster digest/version; stale update conflicts; pre-start revocation prevents the affected player starting; no live substitution bypass.
- Known health/armor damage, friendly fire, suicide/environment death, assist, bomb plant/defuse/explosion and disconnect produce correct normalized events.
- Stable team scores survive a half swap and overtime. One completed MR12/overtime match has correct immutable winner, final stats and ordered terminal evidence.
- Duplicate batch after receiver/provider restart adds no event twice. Different bytes for the same ID fail. Cross-server, cross-match, cross-epoch and wrong-key attempts fail.
- Network timeout after commit is recovered through receipt lookup/retry. Injected storage failure advances no cursor. Missing batches retry in order; irreversible capture loss holds the result.
- Cancellation releases the server and closes admission. Plugin restart never resets an existing epoch unnoticed. Private identity data is absent from public room/event responses.
- Capture CPU/RAM/network and sustained event volume for one real match, then the intended concurrency. Do not turn the earlier five-match/cost estimate into a capacity promise without measurement.

Use [acceptance-report.json](./fixtures/acceptance-report.json). Return actual pass/fail/pending and evidence locations, not just “integration complete.” The next Arena step is implementation and joint acceptance against your staging service, not another request to redesign the identity boundary.
