R2 DEVELOPER REFERENCE / SEPTEMBER 2026

Observations, comparisons
and reproducible evidence.

The R2 sandbox is a deterministic simulation, available without credentials. Authenticated pilot ingress must be enabled and validated for each deployment; it is not a claim of live vendor integration.

Canonical event envelope

Generated schemas: event envelope, agreement, source completeness declaration.

Every observation names its source, identity, tenant and scope. Occurrence and receipt timestamps require explicit timezone offsets. Monetary amounts are decimal strings with at most two fractional digits; currency is explicit.

{
  "schema_version": "2.0",
  "tenant_id": "authenticated-workspace-id",
  "source": "backend",
  "source_instance_id": "operator-1-backend",
  "caused_by": null,
  "source_event_id": "ftd-00001",
  "subject_key": "opaque-subject-00001",
  "event_type": "ftd",
  "occurred_at": "2026-09-09T14:17:00Z",
  "received_at": "2026-09-09T14:17:02Z",
  "operator_id": "operator-1",
  "partner_id": "publisher-01",
  "campaign_id": "campaign-01",
  "geo": "DE",
  "currency": "EUR",
  "amount": null,
  "status": "confirmed",
  "synthetic": false
}

Accepted event types: click, registration, kyc, deposit, ftd, partner_ftd, ngr, commission, payout, lead, qualified_lead, sale, funded_account, partner_conversion and revenue. The transport accepts an object with an events array of 1–500 observations. Deposit, NGR, revenue, commission and payout require an amount. Negative amounts are supported for NGR only. Use opaque identifiers, not names, email addresses or raw personal data.

Ingress and replay semantics

• POST /api/integrity/events: authenticated workspace administrator; disabled by default. The payload tenant must match the session. Synthetic observations cannot enter this route.
• Identity is SHA-256 of the canonical array [tenant_id, source_instance_id, source, source_event_id]. An identical replay returns duplicate. A changed payload with the same identity returns conflict and does not overwrite the original.
• Each event is atomic; a batch is not a transaction. Inspect every event result before retrying. Receipt time is excluded from the payload hash; accepted_at records server acceptance time.
• GET /api/integrity/subjects/:subject_key: tenant-scoped observations, limited to 500 with a truncation flag. It does not infer expected stages without a configured rule.
• GET /api/integrity/demo/:scenario: public synthetic projections. IDs: healthy, callback_gap, delayed, hybrid, identifier_loss, duplicate, revshare, callback_recovery, schema_change and conflicting_delivery.

Configured pilot investigations

PUT /api/integrity/agreements stores an immutable agreement version. GET /api/integrity/agreements lists workspace configurations. POST /api/integrity/investigations evaluates a selected agreement version against accepted events and explicit source coverage declarations. It persists a content-addressed evidence pack, readable at GET /api/integrity/evidence/:evidence_id by that workspace. Writes require an administrator and pilot enablement.

A coverage declaration contains tenant_id, agreement_id, agreement_version, source, complete_from, complete_through, observed_at and an evidence_ref. It attests completeness for the entire configured relationship. This is a source declaration, not an inference from event counts. No portfolio total combines overlapping agreements. Inputs beyond the bounded pilot limit are rejected rather than partially evaluated.

What the comparison means

CPA qualification requires a confirmed FTD, observed registration, first-deposit threshold, KYC where required and the registration-to-FTD window. Missing inputs produce unknown status. RevShare applies to the declared NGR basis with negative carryover before the rate. Hybrid adds independent components. The engine does not exchange currencies or infer legal entitlement.

A missing callback remains pending until its grace period expires and a source completeness declaration covers the deadline. Exact callback correlation also requires caused_by to reference the originating FTD identity within the same tenant, operator and partner. A settlement shortfall compares expected value with observed payout. These measures can describe the same obligation and must not be summed.

NGR, revenue, commission and payout observations require economic_period_start and economic_period_end, separate from occurrence and receipt times. A late payment can belong to an earlier economic period. Agreements declare settlement_due_at when settlement is due after period end. RevShare and carryover pool across the explicitly configured agreement scope; use separate agreements for separate partner balances.

Evidence contract

Evidence JSON includes rule and fixture versions, agreement, formulas, inputs, qualification outcomes, obligation keys and sample event provenance. Interpretation is separate from facts. Sample journeys are labelled and are not a complete event export.

The evidence ID hashes canonical content: UTF-8 JSON, sorted keys, compact separators, with the ID outside the hashed content. Repeating the fixture yields the same artifact. A content hash is not a source signature or external attestation.

Operational evidence and replay

Investigations now include a deterministic operations projection: graph comparisons, source freshness and receipt latency, scoped incident fingerprints, ranked evidence-supported breakpoint candidates, obligations, settlement pool and transparent score denominators. The projection never invents endpoint uptime or a root-cause probability.

GET /api/integrity/operations/workspace returns recent tenant snapshots, not additive portfolio totals. GET /api/integrity/operations/compare/:before/:after compares the same agreement scope at increasing observation times. Future receipts and later completeness declarations are excluded from earlier replay.

Commercial rule vocabulary

CPL requires an explicit qualified_lead conversion, partner_conversion callback and deposit-free qualification. CPA/Hybrid can qualify FTD, sale or funded_account observations. Currency, GEO scope, KYC, first-deposit requirement and qualification window remain explicit. Revenue sharing can use NGR or declared revenue, with evidence-referenced additional period deductions, negative carryover and an agreement-level settlement cap. Source-reported deductions must not be subtracted twice. These are configured expectations, not legal receivables.

Commercial arithmetic currently supports two-decimal currencies: EUR, USD, GBP, CAD, AUD, CHF, SEK, NOK, DKK, BRL, MXN, PLN, CZK, ZAR and INR. The agreement schema rejects unsupported currency precision; it never applies cents to a zero- or three-decimal currency. No FX conversion is inferred.

Integration Studio and connector SDK

Download the mapping contract, connector manifest and connector run schema. Adapters declare auth, source instance, event vocabulary, pagination, rate-limit and retry behavior, completeness semantics and supported actions. REST campaign adapters remain beta; direct database and object-storage transports are planned.

1. Discover a bounded sample using POST /api/integrity/operations/mapping/preview. Explicit dot paths map observed fields; transport-owned tenant, source instance and receipt time cannot be overwritten.
2. Review and approve an immutable version using PUT /api/integrity/operations/mapping. Preview does not activate ingestion.
3. Submit 1–500 reviewed rows to POST /api/integrity/operations/mapping/ingest with mapping_id. The stored mapping controls normalization; canonical ingress returns each event result and an immutable transformation receipt.
4. Run POST /api/integrity/operations/preflight with events, agreement, coverage and as_of. Missing qualification or source coverage remains pending.
5. Record validated runs with POST /api/integrity/operations/connector-runs. Partial or failed runs cannot advance a committed cursor or declare completeness. GET /api/integrity/operations/connector-health exposes schema changes, conflicts and incomplete runs.

Approval, execution and analyst history

GET/POST /api/integrity/operations/cases/:evidence/:incident reads and advances an incident case. Commands include command_id and expected_revision; identical retries are idempotent and competing revisions conflict. The default tenant policy requires another administrator to approve. Internal investigation records can execute; external delivery is unavailable in this orchestrator. Verification requires newer same-scope stored evidence. Notes, typed exceptions and dismissal never rewrite the original monetary calculation.

Schemas: decision command and action policy. A provider HTTP response alone cannot establish success. External execution remains disabled pending registered executors, durable delivery and provider readback validation.

Evidence reports and controlled sharing

JSON, HTML and PDF exports are generated from the same evidence. Pilot report routes are GET /api/integrity/operations/reports/:evidence/html and .../pdf. Download a synthetic PDF report or human-readable report.

POST /api/integrity/operations/shares creates an explicitly redacted summary link with a maximum seven-day lifetime. Bearer secrets are stored as hashes, carried in the URL fragment and sent to the public endpoint through a header. Links can be revoked. Optional counterparty comments and supporting text retain revision history but cannot change evidence, settle an obligation or establish counterparty identity. Internal notes, subject identities and raw source observations are not shared.

Ask Sentinel

POST /api/integrity/operations/ask retrieves structured findings from a selected evidence_id for the supplied question. Every returned statement includes a reference path and projection identity. The implemented mode is deterministic evidence retrieval. An optional LLM explanation or contract-extraction provider is not required or enabled; free-form contract extraction remains a future reviewed workflow.

Expansion changelog

September 2026: operations projection, obligation ledger, receipt-time replay, connector contracts, mapped ingress, guided commercial configuration, evidence reports, controlled sharing, analyst case history and grounded retrieval. No provider was promoted to production certification by this release.

Capability boundaries

Campaign CSV reconciliation is implemented. Meta, Voluum, RedTrack and Everflow have beta API adapter code requiring live validation. Google, TikTok and Shopify API connectors are planned. Commercial configuration and lineage in this showcase use synthetic observations. Automatic platform actions remain disabled pending approval and execution validation.

Fixture release: r2-synthetic-3.0.0. Ten iGaming scenarios, 2,048 fictional subjects, 64 campaigns and 18,432 events in the healthy baseline. These are not customer results.