feat(txodds): add sharp-movement research watcher and match grading

Watches /api/board for odds moves via agent/market.ts's select1x2Market,
queues sharp-movement WANTs for event-mode buyers, and grades delivered
predictions against TxLINE's live score snapshots once matches end.

Author: trilltino

coral-agents/seller-agent/README.md

@@ -22,7 +22,7 @@ In arbiter mode, the seller verifies the escrow buyer as the vault PDA from `DEP
 |---|---|
 | `src/index.ts` | Coral market loop and funding verification. |
 | `src/escrow.ts` | Read-only escrow funding check. |
-| `src/service.ts` | Service delivery for `txline` and `freelance`. |
+| `src/service.ts` | Service delivery for `txline`, `sharp-movement`, and `freelance`. |
 
 ## Harness Adapter
 
@@ -72,6 +72,22 @@ whole point is judging the first loop's output with no visibility into its reaso
 merge above doesn't apply to. Off by default: it doubles the LLM calls per bid decision. See `API.md`
 for the harness-runtime environment reference.
 
+## Sharp-Movement Analysis (opt-in)
+
+Set `SERVICES=txline,sharp-movement` to let this seller also bid on `sharp-movement` WANTs — a report
+on a fixture's *current* market state (magnitude/confidence from the leading outcome's spread, plus
+an LLM read via the same colorful `liveReadOrFallback()` prompt `txline`'s edge action uses) sold in
+response to a WANT the research watcher raised because a real odds move already happened. The seller
+doesn't re-detect the move itself — by the time the WANT exists, `examples/txodds/research/watcher.ts`
+already confirmed one — it just delivers a rich analysis of the fixture as it stands now. Delivered
+payload: `{service, fixtureId, magnitude, confidence, spreadPct, leadingLabel, market, analysis}`.
+`leadingLabel` (`part1` | `x` | `part2`) is what `examples/txodds/research/grade.ts` later grades
+against the real final score — see `research/GRADING.md`.
+
+Normally paired with `examples/txodds/coral/round.ts`'s `SHARP_MOVEMENT_ENABLED=1`, which sets this
+`SERVICES` value automatically and points the buyer's `WANT_FEED_URL` at the watcher's queue instead
+of a fixed rotating arg.
+
 ## Optional Upstream Procurement
 
 Set `PROCURE_RAIL=x402` to have the seller buy an upstream resource for real, paid over x402, after
@@ -101,9 +117,9 @@ Variables:
 |---|---|
 | `SELLER_WALLET` | Payout address. |
 | `AGENT_NAME` | Agent/persona name. |
-| `SERVICES` | Comma-separated supported services. Current coded services are `txline` and `freelance`. |
+| `SERVICES` | Comma-separated supported services. Current coded services are `txline`, `sharp-movement`, and `freelance`. |
 | `FLOOR_SOL` | Base business floor in SOL for a deterministic service; the real floor for an `LLM_DELIVERY_TOKENS`-listed service adds a derived surcharge on top — see Bid Decision Loop above. |
-| `LLM_DELIVERY_TOKENS` | JSON map of service → max_tokens, e.g. `{"txline":260}` — services this seller's delivery code actually calls an LLM for, so that service's floor is derived from real cost instead of `FLOOR_SOL` alone. |
+| `LLM_DELIVERY_TOKENS` | JSON map of service → max_tokens, e.g. `{"txline":260,"sharp-movement":260}` — services this seller's delivery code actually calls an LLM for, so that service's floor is derived from real cost instead of `FLOOR_SOL` alone. |
 | `PERSONA` | Persona label/config. |
 | `STRATEGY` | Pricing posture once `REPUTATION_URL` clearing data is available: `undercut` \| `premium` \| `balanced` (default). No-op without `REPUTATION_URL`. |
 | `BID_REVIEW_ENABLED` | Set to `1` to run a second, adversarial review loop before posting a bid — see above. |

coral-agents/seller-agent/coral-agent.toml

@@ -7,7 +7,7 @@ edition = 4
 [agent]
 name = "seller-agent"
 version = "0.1.0"
-description = "TxODDS marketplace seller. Bids on txline WANTs, verifies arbiter-funded escrow, and delivers a fair-line read."
+description = "TxODDS marketplace seller. Bids on txline WANTs, verifies arbiter-funded escrow, and delivers a fair-line read. SERVICES=txline,sharp-movement also lets it analyze fixtures the research watcher flags as having moved."
 summary = "TypeScript TxODDS seller that competes in CoralOS and settles through arbiter-gated escrow."
 readme = "Bids in the shared market thread (WANT -> BID), issues ESCROW_REQUIRED with settlement=arbiter, verifies the funded vault escrow on DEPOSITED, then delivers the TxODDS read."
 
@@ -18,11 +18,11 @@ expression = "MIT"
 [options]
 SELLER_WALLET = { type = "string", description = "Devnet wallet pubkey that receives payments" }
 AGENT_NAME = { type = "string", default = "seller-agent", description = "Market identity for this seller persona" }
-SERVICES = { type = "string", default = "txline", description = "Inventory; the TxODDS demo uses txline" }
+SERVICES = { type = "string", default = "txline", description = "Inventory - default demo uses txline; set to txline,sharp-movement (with SHARP_MOVEMENT_ENABLED=1 on the round launcher) to also analyze research-watcher-flagged moves" }
 FLOOR_SOL = { type = "f64", default = 0.0005, description = "Minimum bid in SOL" }
 PERSONA = { type = "string", default = "a TxODDS specialist selling verified fair-line reads", description = "Bidding persona" }
 STRATEGY = { type = "string", default = "", description = "Pricing posture once REPUTATION_URL clearing data is available: undercut | premium | balanced (default)" }
-LLM_DELIVERY_TOKENS = { type = "string", default = "", description = "JSON map of service -> max_tokens for services this seller's delivery code calls an LLM for, e.g. {\"txline\":260} - derives that service's floor from real LLM cost instead of FLOOR_SOL alone" }
+LLM_DELIVERY_TOKENS = { type = "string", default = "", description = "JSON map of service -> max_tokens for services this seller's delivery code calls an LLM for, e.g. {\"txline\":260,\"sharp-movement\":260} - derives that service's floor from real LLM cost instead of FLOOR_SOL alone" }
 BID_REVIEW_ENABLED = { type = "string", default = "0", description = "Set to 1 to run a second, adversarial review loop before posting a bid" }
 REPUTATION_URL = { type = "string", default = "", description = "The feed's /api/reputation - when set, gates whether this seller bids at all and feeds clearing-price awareness into pricing" }
 SERVICE = { type = "string", default = "txline", description = "Delivery service; only txline is routed" }

coral-agents/seller-agent/src/service.test.ts

@@ -23,7 +23,7 @@ describe('deliverService routing', () => {
     expect(out).toEqual({
       error: 'unsupported service',
       service: 'coingecko',
-      supported: ['txline', 'freelance'],
+      supported: ['txline', 'freelance', 'sharp-movement'],
     })
   })
 
@@ -110,6 +110,40 @@ describe('deliverService routing', () => {
     expect(out.analysis.note).toContain('deterministic fallback')
   })
 
+  it('delivers a sharp-movement report with magnitude/confidence/leadingLabel', async () => {
+    global.fetch = vi.fn(async (url: string) => {
+      if (url.endsWith('/auth/guest/start')) return { ok: true, json: async () => ({ token: 'jwt' }) }
+      if (url.includes('/api/odds/snapshot/123')) {
+        return {
+          ok: true,
+          json: async () => ([{
+            SuperOddsType: '1X2',
+            PriceNames: ['part1', 'x', 'part2'],
+            Pct: ['70', '20', '10'], // spread(top two) = 50pp -> extreme, confidence clamps to 1
+          }]),
+        }
+      }
+      return { ok: true, json: async () => ([{ FixtureId: 123, Participant1: 'A', Participant2: 'B' }]) }
+    }) as unknown as typeof fetch
+
+    const out = JSON.parse(await deliverService('sharp-movement 123'))
+    expect(out).toMatchObject({
+      service: 'sharp-movement', fixtureId: '123', magnitude: 'extreme', confidence: 1,
+      spreadPct: 50, leadingLabel: 'part1',
+    })
+  })
+
+  it('sharp-movement returns an honest error payload when no priced market exists', async () => {
+    global.fetch = vi.fn(async (url: string) => {
+      if (url.endsWith('/auth/guest/start')) return { ok: true, json: async () => ({ token: 'jwt' }) }
+      if (url.includes('/api/odds/snapshot/')) return { ok: true, json: async () => ([]) }
+      return { ok: true, json: async () => ([]) }
+    }) as unknown as typeof fetch
+
+    const out = JSON.parse(await deliverService('sharp-movement 999'))
+    expect(out).toEqual({ service: 'sharp-movement', fixtureId: '999', error: 'no priced 1X2 market available' })
+  })
+
   it('reports delivery LLM fallback metadata for txline edge analysis', async () => {
     global.fetch = vi.fn(async (url: string) => {
       if (url.endsWith('/auth/guest/start')) return { ok: true, json: async () => ({ token: 'jwt' }) }

coral-agents/seller-agent/src/service.ts

@@ -2,14 +2,19 @@
  * Seller services.
  *
  * `txline` - verified TxLINE fair-line reads for a fixture.
+ * `sharp-movement` - a report on the CURRENT state of a fixture's 1X2 market (magnitude/confidence
+ * from the leader's spread over the field, plus an LLM read), sold in response to a WANT the
+ * research watcher raised because a real move already happened. The seller doesn't re-detect the
+ * move itself - by the time this WANT exists, examples/txodds/research/watcher.ts already confirmed
+ * one - it just delivers a rich analysis of the fixture as it stands now.
  * `freelance` - the generic LLM worker (the freelancer market's baseline seller): the brief goes to
  * the LLM, the deliverable comes back as JSON. Without an LLM key it returns an error payload, which
  * the verifier fails and the buyer refuses to pay for - no-capability sellers don't get released.
  */
 import { complete, llmRuntimeInfo, parseJsonReply, sha256Hex, type LlmUse } from '@pay/agent-runtime'
 
 const TXLINE_BASE = process.env.TXLINE_BASE_URL || 'https://txline-dev.txodds.com'
-const SUPPORTED_SERVICES = ['txline', 'freelance']
+const SUPPORTED_SERVICES = ['txline', 'freelance', 'sharp-movement']
 type DeliveryOrder = { round?: number }
 
 export interface ServiceDelivery {
@@ -51,6 +56,7 @@ export async function deliverServiceResult(request: string, order?: DeliveryOrde
   const [first, ...rest] = request.trim().split(/\s+/).filter(Boolean)
   const service = (first ?? 'txline').toLowerCase()
   if (service === 'freelance') return freelanceService(rest.join(' '), order)
+  if (service === 'sharp-movement') return sharpMovementService(rest.join(' '), order)
   if (service !== 'txline') {
     return {
       payload: JSON.stringify({ error: 'unsupported service', service, supported: SUPPORTED_SERVICES }),
@@ -60,6 +66,67 @@ export async function deliverServiceResult(request: string, order?: DeliveryOrde
   return txlineService(rest.join(' '), order)
 }
 
+function fixtureIdFrom(request: string): string | undefined {
+  return request.trim().split(/\s+/).find((token) => /^\d+$/.test(token))
+}
+
+function hasFinitePrice(market: Record<string, unknown> | undefined): boolean {
+  const pct = (market?.Pct ?? []) as Array<string | number>
+  return pct.some((p) => Number.isFinite(Number(p)))
+}
+
+/** Same selection examples/txodds/agent/market.ts uses for the watcher - kept as a local copy since
+ *  this package is a separate npm workspace with no import path to that one. */
+function select1x2Market(odds: unknown): Record<string, unknown> | undefined {
+  if (!Array.isArray(odds)) return undefined
+  const markets = odds as Array<Record<string, unknown>>
+  return markets.find((m) => String(m.SuperOddsType ?? '').includes('1X2') && hasFinitePrice(m))
+    ?? markets.find(hasFinitePrice)
+}
+
+async function sharpMovementService(request: string, order?: DeliveryOrder): Promise<ServiceDelivery> {
+  const fixtureId = fixtureIdFrom(request) ?? request.trim()
+  const [odds, fixtures] = await Promise.all([
+    txlineGet(`/api/odds/snapshot/${fixtureId}`),
+    txlineGet('/api/fixtures/snapshot'),
+  ])
+  const market = select1x2Market(odds)
+  const fx = Array.isArray(fixtures)
+    ? (fixtures as Array<Record<string, unknown>>).find((f) => String(f.FixtureId) === String(fixtureId))
+    : undefined
+  const teams = fx ? { home: fx.Participant1, away: fx.Participant2, competition: fx.Competition } : undefined
+  const matchup = teams ? `${teams.home} v ${teams.away}` : `fixture ${fixtureId}`
+
+  if (!market) {
+    return {
+      payload: JSON.stringify({ service: 'sharp-movement', fixtureId, error: 'no priced 1X2 market available' }),
+      llm: [deliveryLlm(order, 'skipped', 'no priced market to analyze', 'deterministic market check', { includeModel: false })],
+    }
+  }
+
+  // Magnitude/confidence come from the CURRENT market's decisiveness (spread between the top two
+  // outcomes), not a delta against history - the watcher already confirmed a real move happened
+  // before this WANT existed, so the seller reports the fixture as it stands now rather than
+  // duplicating the watcher's own before/after diffing.
+  const pctNums = ((market.Pct ?? []) as Array<string | number>).map(Number).filter(Number.isFinite)
+  const sorted = [...pctNums].sort((a, b) => b - a)
+  const spread = sorted.length >= 2 ? sorted[0] - sorted[1] : 0
+  const magnitude: 'moderate' | 'sharp' | 'extreme' = spread >= 30 ? 'extreme' : spread >= 15 ? 'sharp' : 'moderate'
+  const confidence = Number(Math.max(0, Math.min(1, spread / 40)).toFixed(2))
+  const names = (market.PriceNames ?? []) as string[]
+  const leaderIndex = pctNums.indexOf(Math.max(...pctNums))
+  const leadingLabel = names[leaderIndex] ?? String(leaderIndex)
+
+  const analysis = await liveReadOrFallback(matchup, odds, market, teams, order)
+  return {
+    payload: JSON.stringify({
+      service: 'sharp-movement', fixtureId, magnitude, confidence,
+      spreadPct: Number(spread.toFixed(1)), leadingLabel, market, analysis: analysis.value,
+    }),
+    llm: [analysis.llm],
+  }
+}
+
 async function freelanceService(brief: string, order?: DeliveryOrder): Promise<ServiceDelivery> {
   try {
     const system =

coral-agents/verifier-agent/src/verify-tools.test.ts

@@ -30,6 +30,11 @@ describe('assessScrutiny', () => {
     expect(assessScrutiny({ payload })).toBe('low')
   })
 
+  it('is low for a well-formed sharp-movement delivery', () => {
+    const payload = JSON.stringify({ service: 'sharp-movement', fixtureId: '1', magnitude: 'sharp', confidence: 0.8, spreadPct: 20, leadingLabel: 'part1', market: {}, analysis: {} })
+    expect(assessScrutiny({ payload })).toBe('low')
+  })
+
   it('is high for a recognized service missing expected keys', () => {
     const payload = JSON.stringify({ service: 'txline-edge', analysis: {} })
     expect(assessScrutiny({ payload })).toBe('high')

coral-agents/verifier-agent/src/verify-tools.ts

@@ -58,6 +58,7 @@ const KNOWN_SHAPES: Record<string, string[]> = {
   'txline-edge': ['teams', 'market', 'analysis'],
   'txline-odds': ['fixtureId', 'odds'],
   'txline-fixtures': ['count', 'fixtures'],
+  'sharp-movement': ['fixtureId', 'magnitude', 'confidence', 'analysis'],
   freelance: ['result'],
 }
 

examples/txodds/README.md

@@ -107,6 +107,32 @@ Requirements:
 
 See `coral/README.md`.
 
+## Research Watcher
+
+The watcher polls `/api/board` every 60 seconds, extracts each fixture's 1X2 market with
+`agent/market.ts`'s `select1x2Market` (the proxy's board attaches `.odds` as an *array* of markets —
+this is the step that turns it into the single `{PriceNames,Pct}` object `research/detect.ts`'s
+`detectEvents` actually needs; skipping it, as this file used to, means no move is ever detected),
+diffs snapshots, and queues jobs when verified odds appear or implied probability moves beyond
+`MOVE_PCT`.
+
+```sh
+npm run proxy
+npm run watch
+```
+
+Watcher endpoints:
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/health` | Health check. |
+| `GET /queue` | Current queued events. |
+| `GET /next` | Pop the next event for event-mode buyer — `odds-move` events request `sharp-movement`, `new-fixture` events request `txline`. |
+
+`buyer-agent`'s event-mode consumes this queue through `WANT_FEED_URL` (see
+`coral-agents/buyer-agent/src/feed/wantFeed.ts`), wired into the CoralOS round by
+`SHARP_MOVEMENT_ENABLED=1` — see `coral/README.md`'s Sharp-Movement Round section.
+
 ## TxODDS Notes
 
 | Item | Value |

examples/txodds/agent/market.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { hasFinitePrice, select1x2Market } from './market.js'
+
+describe('hasFinitePrice', () => {
+  it('is true when at least one Pct value parses as a finite number', () => {
+    expect(hasFinitePrice({ Pct: ['12.5', 'NA', '30'] })).toBe(true)
+  })
+
+  it('is false when every Pct value is missing or unparseable', () => {
+    expect(hasFinitePrice({ Pct: ['NA', 'NA'] })).toBe(false)
+    expect(hasFinitePrice({})).toBe(false)
+    expect(hasFinitePrice(undefined)).toBe(false)
+  })
+})
+
+describe('select1x2Market', () => {
+  it('prefers a priced 1X2 market over other priced markets', () => {
+    const odds = [
+      { SuperOddsType: 'OVER_UNDER', Pct: ['50', '50'] },
+      { SuperOddsType: '1X2_PARTICIPANT_RESULT', Pct: ['40', '30', '30'] },
+    ]
+    expect(select1x2Market(odds)).toBe(odds[1])
+  })
+
+  it('falls back to any priced market when no 1X2 market is priced', () => {
+    const odds = [
+      { SuperOddsType: '1X2_PARTICIPANT_RESULT', Pct: ['NA', 'NA', 'NA'] },
+      { SuperOddsType: 'OVER_UNDER', Pct: ['55', '45'] },
+    ]
+    expect(select1x2Market(odds)).toBe(odds[1])
+  })
+
+  it('returns undefined for a non-array or an all-unpriced odds payload', () => {
+    expect(select1x2Market(undefined)).toBeUndefined()
+    expect(select1x2Market([{ SuperOddsType: '1X2', Pct: ['NA'] }])).toBeUndefined()
+  })
+})

examples/txodds/agent/market.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared market-selection helper for TxLINE odds arrays — `/api/odds/snapshot/{id}` returns an
+ * array of markets (1X2, over/under, etc.); this picks the one match-winner (1X2) market, requiring
+ * an actual priced outcome. Used by `research/watcher.ts` (to build `detect.ts`'s `BoardFixture`
+ * shape correctly — see the module comment there for the bug this fixes) and mirrored as a local
+ * copy in `coral-agents/seller-agent/src/service.ts`, a separate npm workspace with no import path
+ * to this package.
+ */
+
+export function hasFinitePrice(market: Record<string, unknown> | undefined): boolean {
+  const pct = (market?.Pct ?? []) as Array<string | number>
+  return pct.some((p) => Number.isFinite(Number(p)))
+}
+
+/** The 1X2 (match-winner) market, preferred; any other priced market as a fallback. */
+export function select1x2Market(odds: unknown): Record<string, unknown> | undefined {
+  if (!Array.isArray(odds)) return undefined
+  const markets = odds as Array<Record<string, unknown>>
+  return markets.find((m) => String(m.SuperOddsType ?? '').includes('1X2') && hasFinitePrice(m))
+    ?? markets.find(hasFinitePrice)
+}

examples/txodds/agent/txline.ts

@@ -78,6 +78,11 @@ export class TxLineClient {
   odds(fixtureId: number): Promise<unknown> {
     return this.get<unknown>(`/api/odds/snapshot/${fixtureId}`)
   }
+
+  /** Score events snapshot for one fixture. */
+  scores(fixtureId: number): Promise<unknown> {
+    return this.get<unknown>(`/api/scores/snapshot/${fixtureId}`)
+  }
 }
 
 /** International Friendlies — the highest-volume free-tier competition (verified in the catalog). */