Why metagraphed is built the way it is. Each ADR captures one significant decision — its context, the choice made, and the consequences — so the reasoning survives even when the code moves on. Skim these before proposing a structural change.
| ADR | Decision | Status |
|---|---|---|
| 0001 | R2-only data artifacts; commit inputs + contract, self-sufficient publish | Accepted · implemented (publish trigger superseded by 0007) |
| 0002 | Live operational health — 15-min cron prober → store/KV → served live | Accepted · implemented (surface count has grown well past the ADR's figure; mechanism unchanged, store is Postgres since the D1 deletion — see the ADR's status note) |
| 0003 | AI-native layer — agent catalog, llms.txt, remote MCP server |
Accepted · implemented (AI-1–AI-3; tool count has grown well past the ADR's figure; later AI phases tracked in issues) |
| 0004 | Candidate → verified-surface trust model | Accepted · trust model in force; candidate-file intake superseded by 0011 |
| 0005 | Release-channel policy (npm / PyPI / hosted) — runbook in RELEASING.md |
Accepted · implemented (PyPI publishing shipped; the ADR's "blocked on #378" note is resolved history) |
| 0006 | Provenance-tiered storage — git for human inputs, R2 for machine artifacts, dynamic-data serving tier | Accepted (partial) · git/R2 tiers in force; the dynamic-data tier's D1→Postgres trajectory is now owned by 0014; steps 2–4 of the original migration were decided against (#597, #1003), not left pending |
| 0007 | Event-driven data publish + daily floor (replaces the 6h cron) | Accepted · implemented (#1250) |
| 0008 | Subnet data model — one file per subnet; authority + review as fields |
Accepted · implemented (#1678 + surface migration) |
| 0009 | Autonomous contributor review gate (the Gittensory Gate) | Accepted · in use |
| 0010 | Chain-direct block explorer + first-party event indexer | Superseded by 0014 |
| 0011 | Retire the metagraphed-side submission preflight (the gate is external; validate-surface/validate-intake own shape) |
Accepted · implemented |
| 0012 | Chain-data ingestion — bootstrap poller → self-hosted archive indexer (gap-free, prune-proof) | Superseded by 0014 |
| 0013 | Hybrid deployment topology — Cloudflare edge · Railway core · D1→Postgres (Hyperdrive); single project, pruned node | Superseded by 0014 |
| 0014 | Chain-data infrastructure — the real self-hosted core, D1's reliability crisis, and the Postgres serving cutover gating criteria | Accepted · D1 capacity emergency + Hyperdrive connection-affinity fixed (2026-07-10); serving cutover re-verification in progress |
| 0015 | Realtime firehose — Postgres outbox tee (not an indexer push) → box-side relay → Cloudflare Durable Object → SSE/WS/GraphQL-subs/MCP | Accepted · build in progress (#2114, #4980–#4984) |
| 0016 | indexer-rs consolidation — private repo moved into apps/indexer-rs/, history preserved |
Superseded by 0028 — reversed; indexer-rs was extracted back out to metagraphed-infra (#9170) |
| 0017 | u128 precision Phase 3 — no-go on a blanket historical backfill; two of three affected tables have no recoverable old data at all | Accepted · #2923 closed |
| 0018 | Native staking architecture — non-custodial signing, direct-to-RPC broadcast (no relay in v1), mandatory _limit-only slippage protection |
Accepted · build in progress (#5229) |
| 0019 | Native staking origin — path on the main domain, not a subdomain; CSP forward-compat note (connect-src must cover the RPC allowlist) |
Accepted · implemented (#5249) |
| 0020 | Self-serve API key issuance + storage — Postgres row + KV validation cache, hashed secret (departs from the plaintext owner_token precedent), additive rate-limit tier | Proposed · design only (#6734); validation middleware + usage route are #6735/#6736 |
| 0021 | Account-gated fullnode RPC cluster access — wallet-only auth, shared invite-code gate, real pool/failover architecture reusing the public RPC proxy's machinery, reuses ADR 0020's key format/hashing | Accepted · implemented (#6835); network exposure (Cloudflare Tunnel hostname) is the one remaining infra prerequisite |
| 0022 | Paid-tier decision memo — cost model and pricing recommendation | Accepted · content moved to metagraphed-infra (2026-08-07); a commercial memo is not OSS material — see 0028 |
| 0023 | v440 emission pipeline publishing posture — emission_share stays (stage-1 price share) and gains a label; new field names/units fixed; reconstructed values ship only while a harness holds them against chain state; the gate redistributes and does not throttle |
Proposed · decision doc only (#8741); implementation is #8744/#8746/#8749 |
| 0024 | First-party TAO/USD index — publish our own volume-weighted median across venues rather than relay one provider; fixes venue criteria, outlier rule, a three-venue quorum below which nothing publishes, honesty labels, the disclaimer wording, and retirement of the coinpaprika call | Proposed · decision doc only (#8598); authorizes the #8599-#8602 chain, monitored by #8603 |
| 0025 | On-chain TAO/USD index — supersedes 0024; composed as wTAO/WETH × WETH/USDC read from Uniswap pool state at a published block height, because chain state has no terms of service and the ETH leg is ~1,455x deeper than any USD-direct pool; prices wrapped TAO, which the basis label and peg monitoring make explicit | Proposed · decision doc only; authorizes #8600-#8602, monitored by #8603 |
| 0026 | Usage-rollup write path — isolate-scoped buffering with a count-or-age flush, rejecting sampling (the pricing question needs exact counts) and a log-derived rollup (only the Worker's own dispatch produces route_family); counts stay exact, the one new loss mode is isolate eviction with a partial buffer |
Accepted · implemented (#8823) |
| 0027 | MCP access model — public by default, authentication optional and additive; anonymous discoverability is the distribution funnel (registry crawlers are the top clients), so Model C was rejected, and Model A is no longer reachable without deleting a live OAuth resource-server posture; auth buys throughput, not reach, and any future privileged tool is the trigger to revisit that | Accepted · partially implemented (#8967); bearer verification, tiered ceilings and the RFC 9728 / WWW-Authenticate posture were already live, auth_tier telemetry + an accurate server card land with the ADR |
| 0028 | The public/private repo boundary — the test is what a file DOES, not what it is about: serving is public, ingestion and machine operation are private, and the rule itself is public. Supersedes 0016, whose reversed decision was still Accepted and still pointed at a directory that no longer exists | Accepted · implemented (metagraphed-infra#374) |
ADRs are immutable records of a decision at a point in time — don't rewrite an accepted one when reality moves. Instead:
- A decision is replaced → write a new ADR and set the old one's status to Superseded by ADR-NNNN (see 0001 → 0007).
- A decision lands or stalls → update only its Status line, and the row above, so this index reflects reality at a glance.
New ADR: copy the header shape (Title · Status · Date · Context · Decision · Consequences), take the next number, and add a row here.