[zenasben5]

Summary

This PR makes the oracle trust engine cover the money path. It has four commits, one per issue, and each builds on the one before:

#	Commit	Problem it closes
1	feat(oracle): route CoinGecko, Horizon and DeFiLlama through the source adapter registry	Production sources sat behind bespoke fetch-and-parse blocks, so trust controls could not apply to them uniformly.
2	feat(oracle): durable, ordered evidence buffer that survives Postgres outages	A Postgres outage dropped readings (holes in the audit trail) or would block polling.
3	feat(claim): make consensus decisions the sole input to settlement	The claim scanner paid out on whatever single reading the monitor produced.
4	feat(oracle): smooth each source over time before cross-source consensus	One bad sample from a good source could flip a trigger.

Reviewing commit by commit is recommended. Each commit message explains its design in more detail.

1. Source adapters: one ingestion path

• New OracleSourceAdapter interface and OracleSourceRegistry (src/oracle/adapters/).
• CoinGeckoAdapter (USDC price, XLM 24h change), HorizonAdapter (latest ledger, used as chain context) and DefiLlamaAdapter (protocol TVL 24h change) replace the inline axios blocks. OracleService has no fetch logic of its own any more.
• The registry applies the same pipeline to every source:
  quarantine gate → fetch (timeout) → schema check → canonicalize (finite, plausible bounds, fixed precision) → freshness (per-metric max age, future-timestamp rejection) → evidence.
• Evidence kept per response: URL, HTTP status, SHA-256 of the body, size and a short excerpt.
• Quarantine: N consecutive failures, or one malformed or out-of-bounds response, sidelines a source for a metric. After the cooldown it gets a half-open probe.
• Observability: refract_oracle_source_observations_total{source,metric,outcome} and refract_oracle_source_quarantines_total.
• OracleReading now carries sources and observations. The degraded fail-safe behaviour is unchanged.

2. Evidence buffer: complete and ordered through DB outages

append() ─▶ seq assigned ─▶ local fsync'd NDJSON spool ─▶ resolves (Postgres not involved)
                                    │
             background flusher ────┘──▶ Postgres, in seq order, batched, exponential backoff

• No drops: readings wait in the spool, which survives restarts and is replayed on boot.
• No blocking: polling only waits for a local append.
• Ordered and idempotent: flushing is head-of-line by seq, and ON CONFLICT (seq, recorded_at) DO NOTHING makes crash replays harmless.
• Gaps are explicit, never silent: if even the local write fails (disk full or size cap), seqs are not reused. The lost run is written to oracle_evidence_gaps once writes recover, and append() throws EvidenceNotDurableError so that settlement fails closed (see commit 3).
• Torn final lines from a crash mid-write are discarded on recovery.
• Gauges: refract_oracle_evidence_pending, refract_oracle_evidence_lost_total, refract_oracle_evidence_complete.
• Migration src/db/migrations/004_oracle_evidence_sequence.sql adds seq, kind, payload, ingested_at, the unique index and the gaps table.
  • ⚠️ It also drops chk_oracle_value_nonneg. That check rejected every negative MarketCrash or TVL reading, which are exactly the readings that matter, and it would have wedged the ordered replay.
• docker-compose gets an oracle-evidence volume, and the Dockerfile creates the spool directory with node ownership.

3. Consensus-gated settlement

• ConsensusService produces a ConsensusDecision per coverage type:
  • quorum: else insufficient
  • spread within maxSpread: else conflicted
  • confidence = coverage × agreement, must reach the configured minimum
  • degradation: degraded is still actionable if quorum holds
  • recorded in the evidence trail: else unrecorded
• The aggregated value is the median of the inputs. Mock-tier sources never count toward quorum.
• ClaimService now depends only on ConsensusService, not on OracleService. The payout path accepts only a SettlementAuthorization, and authorizeSettlement() issues one only for an actionable, triggered, recorded decision of the matching coverage type.
• Every settled ClaimResult carries decisionId (<CoverageType>@<evidence seq>), which links the payout to its observations and HTTP evidence.

Behaviour change: LiquidationShield and FlightDelay have no live source, so their decisions are always insufficient. They no longer settle automatically on Math.random() mock values.

4. Temporal smoothing

• TemporalSmoother keeps a rolling window per (source, metric, subject), fed from every registry observation (scheduler polls and consensus rounds).
• A source contributes the median of its window, so a single spike cannot move it, while a sustained move comes through.
• A source counts only after it has MIN_SAMPLES distinct samples spanning at least MIN_SPAN_MS. Until then it reports "warming up".
• Samples are keyed by upstream observedAt, so a cache replaying the same response adds nothing and cannot overwrite the first value.
• Decision inputs record rawValue, smoothed value, samples and spanMs.

Configuration (all optional, with safe defaults)

Variable	Default
ORACLE_QUARANTINE_AFTER_FAILURES / ORACLE_QUARANTINE_MS	3 / 300000
ORACLE_EVIDENCE_SPOOL_DIR / ORACLE_EVIDENCE_SPOOL_MAX_BYTES	.data/oracle-evidence / 256 MiB
ORACLE_CONSENSUS_MIN_SOURCES	1 (each metric has one live source today; raise to 2 when a second source lands)
ORACLE_CONSENSUS_TARGET_SOURCES / ORACLE_CONSENSUS_MIN_CONFIDENCE	2 / 0.5
ORACLE_CONSENSUS_DECISION_TTL_MS	30000
ORACLE_SMOOTHING_WINDOW_MS / _MIN_SAMPLES / _MIN_SPAN_MS / _MAX_SAMPLES	15 min / 3 / 2 min / 60

STELLAR_HORIZON_URL (the name docker-compose uses) is honoured, with HORIZON_URL as a fallback.

Testing

• 57 new or rewritten unit tests across adapters, registry, OracleService, spool, buffer, repository, consensus and smoother, plus 11 for the consensus-gated ClaimService. All pass, and each commit passes on its own.
• Covered scenarios:
  • Postgres down, then recovery with in-order drain
  • restart replay without seq reuse
  • torn-write recovery
  • spool-full gap recording and fail-closed behaviour
  • quorum, conflict, confidence and unrecorded blocks
  • a single depeg print not triggering, while a sustained one does
  • CDN replay dedupe

Pre-existing repo breakage (not fixed here)

main does not currently build or run tests, independent of this PR:

• package.json is empty.
• app.module.ts has merge debris and imports modules that don't exist.
• Several files are 0 bytes, including claim.module.ts, claim-settlement.service.ts, oracle-publisher.service.ts, oracle.controller.ts, db.module.ts and oracle.scheduler.spec.ts.
• src/parameters/ is missing.

How this PR was verified despite that:

• The new code was typechecked with tsc --strict and tested with jest in an isolated harness.
• ClaimService was typechecked against a stub of the empty ClaimSettlementService, because the real file has no exports.
• This PR rewrites oracle.service.ts and oracle.module.ts, which were also empty. OracleModule now exports ConsensusService and OracleEvidenceBuffer, so a restored ClaimModule only needs to import OracleModule, as it did before.

Deployment notes

• Apply src/db/migrations/004_oracle_evidence_sequence.sql.
• Mount a persistent volume at ORACLE_EVIDENCE_SPOOL_DIR in every deployed environment.
• After boot, a source becomes actionable after about 2–3 minutes (smoothing warm-up at a 60s poll).

Closes #227
Closes #228
Closes #229
Closes #230

[drips-wave]

@zenasben5 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits