GameCult/Stonks
Watch
9
0
Fork
You've already forked Stonks
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Stonks/docs/architecture.md
Meta Vens 8f49d610d8 Publish Stonks provider boundary records
2026-06-16 12:04:26 +01:00

1.9 KiB
Raw Permalink Blame History

Stonks Architecture

Objective

Expose market price and volume pulse as a provider-owned CultMesh/Eve surface so Odin can aggregate it and renderers can lower it without owning market state.

Current Mechanism

Public market endpoints
  -> Stonks poller
  -> request-event, market-snapshot, provider-advertisement,
     command-boundary, transport-profile, and Eve-surface CultCache documents
  -> normalized market snapshot with provenance, freshness, and request history
  -> provider-owned Eve/CultUI surface
  -> /eve/deck WebSocket + /eve/deck/providers manifest
  -> Odin interface ingestion
  -> Eve / Nightwing / agent projection

Stonks refresh completion
  -> idunn.daemon_health raw CultNet document
  -> cultnet.transport.rudp.v0 schema channel
  -> Idunn keepalive store and decision cycle

Invariants

  • Market sources own prices and volumes.
  • Stonks owns polling, normalization, provenance, and surface publication.
  • Stonks owns request-event persistence; Odin may publish request events on the marquee, but it does not create or mutate them.
  • Odin owns discovery and aggregation, not market truth.
  • Renderers lower the Stonks surface only.
  • Stonks does not trade, advise, custody funds, or infer portfolio intent.
  • The /health, /market/state, and /eve/deck HTTP/WebSocket surfaces are compatibility projections. Idunn liveness is daemon-published RUDP health, not an Odin-owned curl probe.
  • Odin should ingest Stonks provider advertisement, command boundary, transport profile, market snapshot, and Eve surface from scratch/stonks/stonks-state.cc. The HTTP/WebSocket endpoints are lowerings over that store.
  • Refreshes are serialized because each refresh publishes daemon health after updating the market snapshot.

Future Cut

When a typed CultMesh market feed exists, replace public polling with provider documents while preserving the same normalized snapshot and Eve surface.