import type { Metadata } from "next";
import Link from "next/link";
import { Page, PageHeader } from "@/components/ui/section";

export const metadata: Metadata = { title: "Methodology", description: "How Market Atlas forms canonical prices: observations, consensus, freshness semantics, confidence, source families, reliability scores and derived metrics.", alternates: { canonical: "/methodology" } };

export default function MethodologyPage() {
  return (
    <Page>
      <PageHeader kicker="Transparency" title="Methodology" lead="Market Atlas never shows a value without saying where it came from, how fresh it is, and how many independent observers agree. This page explains each step from a raw payload to a canonical quote." />
      <div className="prose-ma max-w-3xl">
        <h2>1. Observations, not prices</h2>
        <p>
          The atomic unit is an <strong>observation</strong>: one field (last price, bid, ask, volume, yield…) for one instrument, from one source, at one time. Every observation keeps its source timestamp when the source publishes one, the moment Market Atlas received it, its data-rights status, its real-time class and a reference to the raw payload it was extracted from (layers L0 raw → L1 parsed → L2 normalized → L3 canonical → L4 derived).
        </p>
        <h2>2. Instrument resolution</h2>
        <p>
          A ticker alone never identifies a security. Each source symbol (<code>BTC-USD</code>, <code>BTC/USD</code>, <code>BTCUSD</code>, <code>BRK.B</code>, <code>BRK-B</code>…) is resolved through a per-source alias table to one stable Market Atlas id such as <code>eq_us_xnas_aapl</code>, <code>crypto_btc_usd</code>, <code>fx_eur_usd</code> or <code>index_us_spx</code>. USD and USDT crypto pairs are different instruments. Listed US equities come from the Nasdaq Trader symbol directories and the SEC company directory (CIK), which is how filings link to instruments.
        </p>
        <h2 id="source-mesh">3. Source Mesh: observation types, comparability, roles</h2>
        <p>
          <strong>One instrument → many observers → one canonical market state.</strong> Every observation carries an <em>observation type</em> that says what the value <em>is</em>: <code>TRADE</code> (last trade on a venue), <code>MID</code>, <code>QUOTE</code> (bid/ask), <code>INDEX_VALUE</code>, <code>INDICATIVE</code>, <code>STABLECOIN_PROXY</code> (a fiat rate implied by a USDT/USDC market), <code>DERIVED</code>, <code>OFFICIAL_FIX</code> (central-bank fixing), <code>REFERENCE_RATE</code> (policy rate, par yield), <code>SETTLEMENT</code>, <code>EOD_CLOSE</code>, <code>NAV</code>. Types map to three <em>comparability classes</em>: <strong>LIVE</strong> (trades, mids, quotes, index values, proxies), <strong>FIX</strong> (official fixings, reference rates) and <strong>EOD</strong> (settlements, daily closes). Values of different classes are never compared: an ECB fixing at 16:00 CET is not a live EUR/USD mid, and last week&apos;s close is not divergent from today&apos;s. The canonical value uses the best class available — live real markets first, then official fixings, then end-of-day closes, then live proxies alone (labelled <em>indicative</em>) — and other classes are reported in the matrix as <code>not_comparable</code>. Inside a class, observations must also be close in time (live: within two minutes of the freshest; fixings/closes: same UTC day), otherwise <code>temporal_mismatch</code>.
        </p>
        <p>Each fresh, comparable observation then plays one of three roles:</p>
        <ul>
          <li>
            <strong>Votes</strong> — observations from real markets and official publishers set the canonical value (weighted median).
          </li>
          <li>
            <strong>Confirms</strong> — proxies (stablecoin markets, derived crosses, indicative values) join the median with reduced weight (35 % when a real market exists) and <em>never</em> count as an independent family; the number of proxies agreeing within 50 bp is shown as <code>proxy_count</code>.
          </li>
          <li>
            <strong>Validates</strong> — sources whose data rights forbid redistribution (for example nasdaq.com&apos;s delayed quote) are compared to the consensus but never vote and are never displayed (<code>validation_only</code>); agreement within 25 bp raises confidence, disagreement beyond 50 bp is flagged <code>validator_disagrees</code>.
          </li>
        </ul>
        <p>
          <strong>Redundancy targets.</strong> Instruments are tiered: <em>A</em> (majors — AAPL, SPX, BTC, EUR/USD, gold…) target ≥ 3 independent families and 5 observations; <em>B</em> (liquid crypto, FX, indices, ETFs) ≥ 2 families and 3 observations; <em>C</em> (long tail) 1 family and 2 observations; <em>D</em> (official reference series such as Treasury par yields or policy rates) one official source is the truth. The <Link href="/coverage">source coverage</Link> page scores every quoted instrument against its target (65 % family attainment + 35 % observation attainment) and lists the expansion queue.
        </p>
        <p>
          <strong>Statistical lineage.</strong> Two sources whose last prices coincide (identical value within two seconds) on at least 92 % of 120+ aligned samples very likely redistribute the same upstream vendor. Market Atlas then treats them as one family — even without contractual knowledge of the vendor — and publishes the pair on the coverage page. Hidden commercial relationships are never asserted; the similarity is shown as what it is.
        </p>
        <h2>4. Consensus</h2>
        <p>For every instrument and field, the engine keeps the latest observation of each source, then computes:</p>
        <ul>
          <li>
            <strong>Freshness window.</strong> Real-time observations count for 15 seconds, delayed feeds for 30 minutes, indicative values for one hour, end-of-day values for ten days (weekly-refreshed official datasets). While a venue is closed, the last session value stays valid for up to four days and is reported as <em>at close</em>. Anything older is excluded and marked <em>stale</em>.
          </li>
          <li>
            <strong>Comparability.</strong> Only observations of the canonical class (see section 3) that are close in time are compared; other classes are reported as <code>not_comparable</code> or <code>temporal_mismatch</code>, never mixed and never counted as divergence.
          </li>
          <li>
            <strong>Weights.</strong> weight = source reliability × timestamp quality (exchange 1.0, source 0.9, connector 0.75) × real-time class (real time 1.0, delayed 0.6, indicative 0.5, end of day 0.4) × official-source bonus (×1.6 for rates and yields, ×1.15 otherwise) × freshness decay. For crypto, a venue&apos;s weight also scales with its share of the 24-hour notional volume among voters, so a thin venue never outweighs the deepest markets.
          </li>
          <li>
            <strong>Source families.</strong> Sources believed to share an upstream — declared, or inferred statistically — count as one vote; extra members of a family receive a quarter of their weight. The number of <em>independent sources</em> shown everywhere is the number of distinct <em>voting</em> families; proxies and validators are counted separately.
          </li>
          <li>
            <strong>Outliers.</strong> With three or more candidates, values more than 2 % away from the weighted median are excluded (reason <code>outlier</code>).
          </li>
          <li>
            <strong>Canonical value.</strong> The weighted median of the remaining candidates. Dispersion is the spread between the highest and lowest included value, in basis points.
          </li>
        </ul>
        <h2>5. Confidence</h2>
        <p>
          Confidence is a 0–1 score of Market Atlas&apos; own agreement, redundancy and freshness — never a prediction or a view on the instrument: <code>0.15 + 0.35 × agreement + 0.25 × redundancy + 0.10 × freshness + 0.15 × mean reliability</code>, capped at 0.995 so the interface never claims false precision. Agreement falls to zero at 1 % dispersion; redundancy is <code>1 − e^(−(families + ½ proxies + ½ validators)/2)</code> (one family ≈ 0.39, three ≈ 0.78, five ≈ 0.92); freshness decays with the age of the newest observation (fixed at 1 while a venue is closed). A single stale observation yields confidence 0.
        </p>
        <h2>6. Data status labels</h2>
        <table>
          <thead>
            <tr>
              <th>Label</th>
              <th>Meaning</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>Live</td>
              <td>At least one real-time source within the freshness window (crypto venue feeds).</td>
            </tr>
            <tr>
              <td>Delayed</td>
              <td>Value from a feed that is contractually delayed (Cboe quotes are 15 minutes behind).</td>
            </tr>
            <tr>
              <td>At close</td>
              <td>The venue is closed; the value is the last session's, shown with the closing time.</td>
            </tr>
            <tr>
              <td>End of day</td>
              <td>Official or licensed daily value (ECB/Bank of Canada fixings, Treasury par yields, daily bars).</td>
            </tr>
            <tr>
              <td>Indicative</td>
              <td>Only proxies (stablecoin markets, derived crosses) are fresh — the value is a live approximation, not a quote from a real market for the instrument.</td>
            </tr>
            <tr>
              <td>Stale</td>
              <td>No source within its window; the last known value is displayed with its age and confidence 0.</td>
            </tr>
            <tr>
              <td>Withheld</td>
              <td>The value exists but its data rights do not allow public redistribution; provenance metadata is still shown.</td>
            </tr>
          </tbody>
        </table>
        <h2>7. Source reliability</h2>
        <p>
          Each connector carries an operational score from 0 to 100: 40 % availability (share of minutes healthy), 20 % parse success, 15 % latency (p95 under 1 s = full marks), 15 % connection stability, 10 % error rate. It measures how well the integration behaves, not the quality of the venue. The best score across a source's connectors feeds the consensus weight.
        </p>
        <h2>8. Events</h2>
        <p>
          Ticks are noisy; events are meaningful. Derived events use per-instrument baselines: a <em>price move</em> fires when the change since the last event exceeds max(0.5 %, 8 × the typical tick move); <em>session highs/lows</em> require 200 observations and a 0.1 % improvement; a <em>volatility spike</em> compares realized volatility over the last 30 ticks with an exponentially weighted baseline (≥ 4×); <em>source divergence</em> fires when voting sources of the same comparability class disagree by more than 100 bps (at most once an hour per instrument). Venue and regulator events (halts, filings) are deduplicated on their native identifiers; additional sources confirming the same event increase its source count instead of creating a duplicate.
        </p>
        <h2>9. Bars and derived metrics</h2>
        <p>
          One-minute bars are aggregated from canonical prices and rolled up to 5m/15m/1h/1d; daily history for equities, indices, FX, crypto and continuous futures comes from licensed end-of-day bars. Market Atlas never overwrites an official daily bar with a derived one. Returns, volatility, drawdown, correlation, breadth and “what changed” counts are computed from these bars and labelled <em>derived</em>.
        </p>
        <h2>10. Market hours</h2>
        <p>
          Session states (pre, open, post, closed, holiday, early close) come from a calendar engine using IANA time zones, per-venue sessions and holiday tables; US holidays are refreshed from the Nasdaq Trader schedule page by an HTML change-detection connector. Nothing is hard-coded to 09:30–16:00.
        </p>
        <h2>11. Limitations</h2>
        <ul>
          <li>Equity and index quotes are delayed 15 minutes; Market Atlas does not hold real-time US equity redistribution rights.</li>
          <li>Rates and yields are official reference values, published once a day. Major FX pairs are live from Kraken&apos;s and Bitstamp&apos;s fiat markets (real trades, keyless) with stablecoin-market proxies as confirmations; central-bank fixings remain the FIX-class reference and are never mixed with live values.</li>
          <li>Intraday history starts when Market Atlas first observed an instrument live; gaps are never interpolated.</li>
          <li>Coverage measures Market Atlas observation, not market size or quality.</li>
        </ul>
        <p>
          See also: <Link href="/licensing">data rights</Link>, <Link href="/sources">sources</Link>, <Link href="/developers">developer documentation</Link>.
        </p>
      </div>
    </Page>
  );
}