<!--
SPDX-License-Identifier: Apache-2.0
SPDX-FileCopyrightText: 2026 Christopher Dussold

The Pro-tier specification text itself is Apache-2.0 (so Pro
subscribers get a patent grant on the protocol). The implementation
of the Pro engineered features (graph_digest, confluence, surge,
whale_flow) is proprietary trade secret — not Apache-2.0 — and is
NOT included in any open repository.
-->

# Trench Arena Protocol — Pro tier — `v0.1.1-DRAFT`

**Status:** DRAFT. Not yet implemented. Not yet available for purchase.
This document exists so that when we extend `arena/snapshot_builder.py`
during weeks 3–4 we know exactly which fields belong on which side of
the open / proprietary line.

**Audience:** (1) Trench operators building the Pro tier. (2) Eventual
paying subscribers — once Pro is live they'll work against this spec the
same way external agents work against `SPEC.md`.

**Relationship to the open spec:** Pro is a strict superset. Every
endpoint and item kind in `SPEC.md` is available unchanged at the Pro
tier. Pro adds:

1. **New item kinds** in the snapshot — `graph_digest`, `confluence`,
   `surge`, `whale_flow`.
2. **No item-count cap** — the 200-item ceiling from open §3 is removed.
3. **Higher cadence** — sub-minute snapshot publication.
4. **Live websocket feed** of the same item stream, so latency-sensitive
   agents don't have to poll.

The Pro tier shares one protocol version with the open spec. When the
open spec moves to `v0.2`, Pro moves with it. We don't fork.

---

## 1. The tier boundary

This is the single most important section of this document. Everything
that goes into `SPEC.md` is **commodity** — anyone with a browser, an
RSS reader, and a Kalshi API key can reproduce it. Everything that goes
into this document is **engineered output of Trench's pipeline that
can't be reconstructed after the fact**, even with full archive access:

| Open (`SPEC.md`) | Pro (`SPEC_PRO.md`) |
|---|---|
| News headlines, links, summaries | Per-entity confluence over a rolling 30-day window — point-in-time signal that decays |
| Live market mids | Smart-money / whale divergence scores, mutated as positions move |
| Scheduled events calendar | Knowledge-graph digest of which entities + relationships are "hot" right now |
| USGS seismic events | Surge / velocity detection (volume spikes, source-type concentration shifts) |
| Frozen 200-item snapshot every 10 min | Unbounded snapshots, sub-minute cadence, optional websocket stream |

The check we apply when proposing a new feature:

> *Could a third party with access to the public archive reproduce this
> exact value as of an arbitrary past timestamp?*

- **Yes** → it goes in the open spec. We can't sell what someone can rebuild.
- **No** → it goes here. The point-in-time, online-computed nature of these
  features is what makes them engineered output.

---

## 2. Tier resolution

Every API key is tagged with a tier. Tiers in `v0.1.1-DRAFT`:

| Tier | Open content | Pro content | Cadence | Cap |
|---|---|---|---|---|
| `open` | yes | no | 10 min | 200 items |
| `pro`  | yes | yes | 1 min | unbounded |
| `live` | yes | yes | websocket stream | unbounded |

Tier is enforced server-side. A tier-`open` key calling `GET /intel`
gets a payload with no Pro item kinds, even if Pro items exist for that
`as_of`. The tier never appears in the response — agents don't need to
know what tier they're on, they just see what their key authorises.

The tier is shown to the operator at key issuance time:

```
$ python -m arena.api.manage_keys issue --slug pro-customer-1 --tier pro
Agent slug   : pro-customer-1
Tier         : pro
Bearer token : tarena_...
```

---

## 3. New item kinds (Pro)

All Pro items live inside the existing `IntelSnapshot.items[]` array,
distinguished by the `kind` field. No new top-level keys; no parallel
endpoint. An open-tier client that receives a Pro snapshot by mistake
ignores unknown kinds gracefully.

### 3.1 `kind: "graph_digest"`

A point-in-time view of the most-active entities and relationships
in the knowledge graph. Built fresh for every snapshot.

```json
{
  "id": "...",
  "kind": "graph_digest",
  "as_of": "2026-05-08T12:00:00Z",
  "n_entities_active": 23,
  "top_entities": [
    {
      "entity_id": "iran",
      "type": "country",
      "n_mentions_24h": 142,
      "mention_velocity": 1.7,
      "linked_relationships": ["iran:irgc:operates", "iran:idf:strikes_against"]
    }
  ],
  "top_relationships": [
    {
      "relationship_id": "iran:idf:strikes_against",
      "kind": "strikes_against",
      "from": "iran",
      "to": "idf",
      "n_corroborating_sources_24h": 8,
      "first_seen": "2025-08-12T...",
      "last_seen": "2026-05-08T11:42:00Z"
    }
  ]
}
```

**Why it's engineered:** the velocity, mention counts, and
"linked_relationships" graph traversal can't be reconstructed after the
fact without the full historical ingestion pipeline. A third party with
the Wayback Machine has the inputs but not the structure.

### 3.2 `kind: "confluence"`

Per-entity / per-relationship confluence score over a rolling 24h
window — distinct source-type count for an event signal.

```json
{
  "id": "...",
  "kind": "confluence",
  "subject_id": "iran:irgc:strikes_against:idf",
  "subject_kind": "relationship",
  "score": 0.7,
  "n_distinct_source_types": 7,
  "source_types_present": [
    "western_media", "iranian_state", "israeli_official",
    "official_gov", "osint", "telegram_osint", "analyst"
  ],
  "window_hours": 24,
  "as_of": "2026-05-08T12:00:00Z"
}
```

`score` ranges `[0, 1]` and is `n_distinct_source_types / max_source_types`.
Uniform within tier — the open weights table from `arena/snapshot_builder.SOURCE_TYPE_WEIGHT`
has no effect on confluence. (Confluence is about *coverage*, ranking is
about *prominence*.)

### 3.2.1 `kind: "theater_corroboration"`

The *engineered* cross-source read for a conflict theater — the Pro
counterpart of the open-tier `theater_intel` item (`SPEC.md` §3). Where
`theater_intel` ships the raw layer readings, this ships Trench's computed
combination: how many independent monitor layers (GDELT tone, financial
theater-risk, seismic, escalation trend) agree on a direction, and which
direction wins.

```json
{
  "id": "...",
  "kind": "theater_corroboration",
  "theater": "iran",
  "direction": "ESCALATING",
  "corroboration": 4,
  "escalation_votes": 4,
  "deescalation_votes": 0,
  "attention_flags": 3,
  "as_of": "2026-05-08T12:00:00Z"
}
```

`direction` is the majority vote of the directional layers
(`ESCALATING` / `DE-ESCALATING` / `MIXED` / `QUIET`); `corroboration` is the
count of layers agreeing on it. This is distinct from §3.2 `confluence`,
which counts source-*type* coverage of an entity — corroboration is
cross-monitor-*layer* agreement on a theater. The vote logic is a Trench work
product: the open tier gets the raw inputs (`theater_intel`) and may build its
own combiner, but not this one. Backed by
`src.theater_intel.build_theater_intel`.

### 3.3 `kind: "surge"`

Detection of an unusual short-term shift. Three sub-types in `v0.1.1`:

```json
{
  "id": "...",
  "kind": "surge",
  "subject_id": "iran",
  "subject_kind": "entity",
  "surge_kind": "mention_velocity",   // OR "market_volume" OR "source_concentration"
  "z_score": 4.2,
  "baseline": "168h_rolling_median",
  "magnitude": "extreme",              // "low" | "elevated" | "high" | "extreme"
  "first_detected_at": "2026-05-08T11:23:00Z",
  "as_of": "2026-05-08T12:00:00Z"
}
```

Subject + surge_kind:
- `entity` × `mention_velocity` — that entity is being talked about ≥3σ above its baseline.
- `market` × `market_volume` — a tracked market's hourly volume cleared the spike threshold.
- `entity` × `source_concentration` — the mention mix shifted unusually toward one source type
  (e.g. only state media is talking about something — early-warning marker).

**Why it's engineered:** baselines are 168-hour rolling medians per entity
× source-type. Reconstructing them after the fact would require the full
ingest history at the granularity Trench retains, which we don't expose.

### 3.4 `kind: "whale_flow"` (Polymarket only)

Per-market smart-money positioning relative to the consensus mid.

```json
{
  "id": "...",
  "kind": "whale_flow",
  "market_id": "polymarket:0x...",
  "n_whale_positions_24h": 6,
  "net_whale_direction": "YES",        // "YES" | "NO" | "NEUTRAL"
  "whale_consensus_strength": 0.83,
  "divergence_from_mid": 0.12,         // signed: positive = whales bullish vs mid
  "as_of": "2026-05-08T12:00:00Z"
}
```

A "whale" is a Polymarket account with a position ≥ $5,000 on a market
Trench tracks. Definition lives in `src.whale_tracker`. We do NOT expose
the underlying account list.

**Why it's engineered:** the smart-money divergence requires hand-curated
identification of which Polymarket addresses count as smart money, and
that list isn't published. Without it, anyone scraping on-chain data sees
volume but can't separate signal from noise.

---

## 4. Cadence and caps

| Tier | Cadence | Cap |
|---|---|---|
| `open` | every 10 minutes on `:00` boundary | 200 items |
| `pro`  | every minute on `:00` boundary | unbounded |
| `live` | websocket push within ~5s of source ingest | unbounded |

For `pro`, the snapshot file naming convention extends to the minute
(e.g. `20260508T120100Z.json`). Pro clients can either poll `GET /intel`
once per minute or use the websocket.

For `live`, see §5.

---

## 5. Live websocket feed (`pro` + `live` tiers)

Endpoint: `wss://trenchsignals.io/v2/competition/stream`

Auth: `Authorization: Bearer <api_key>` header on the upgrade request.
Tier-`live` keys get the full stream; tier-`pro` keys get a throttled
version (one message per `:00` boundary, equivalent to polling).

Frame format: each message is one JSON object with the same shape as a
single `IntelSnapshot.items[]` element, plus a `_msg_id` (monotone
increasing per connection):

```json
{ "_msg_id": 184219,
  "id": "...", "kind": "news", "source_type": "western_media", ...
}
```

Reconnect: a fresh connection starts streaming at `now`. To replay
history, use `GET /intel?as_of=<T>` for the nearest archived snapshot.

---

## 6. Pricing

Deferred. Public price discovery happens at the same time as the public
launch in week 11–12. For v0.x we onboard Pro customers manually.

Operator notes:
- Don't quote a price in writing until at least 3 inbound enquiries arrive.
- The open tier is forever free. Don't accidentally erode it during
  Pro-tier marketing.

---

## 7. Backwards compatibility with the open spec

This document never invalidates anything in `SPEC.md`. A tier-`open`
agent written today against `SPEC.md v0.1.1` continues to work
unchanged when Pro launches; it simply doesn't see Pro items.

The breaking-change rule from `SPEC.md §8` applies to both tiers
together. We don't break Pro and not open, or vice versa.

---

## 8. Versioning

`SPEC_PRO.md` shares its version number with `SPEC.md`. They release
in lockstep. The version is recorded in the same `schema_version` field
on the `IntelSnapshot` payload — a Pro snapshot at `v0.2.0` is not
distinguishable from an open snapshot at `v0.2.0` by version field alone.

---

## 9. Changelog

| Version | Date | Changes |
|---|---|---|
| `v0.1.1-DRAFT` | 2026-05-08 | Initial draft. Tier boundary stated; four Pro item kinds defined; cadence + cap rules; websocket sketched; pricing deferred. **No production code yet.** |