# advantage > Every supported model, what it does, and why it follows from the last: see [SUPPORTED.MODELS.md](SUPPORTED.MODELS.md). A small module that connects **advantage math** to a **store of knowledge**, so it can answer: *which advantage should I draw on, and what must I check before I do?* ``` evidence ──▶ C core: mean, stddev, confidence ──┐ ├─▶ score = mean × confidence × trust ─▶ ranked counsel assumptions (held / doubted) ──▶ trust ─────────┘ ``` ## Parts | File | Role | |------|------| | `advantage.{h,c}`, `advantage.{hpp,cpp}` | C math core + C++ wrapper: `advantage_value`, `advantage_mean`, `advantage_stddev`, `advantage_confidence`; `advantage::mean_checked` rejects mismatched series | | `advantages.xml`, `advantage_store.*` | Knowledge store: sources, assumptions, knowledge strings, evidence | | `counsel.*` | Joins the two: ranks sources with scores, things to verify, and cautions | | `enrich.*` | Opt-in, allowlisted fetch of extra (untrusted) knowledge lines | | `analyze.cpp` | CLI over all of the above | | `trading/` | Eleven trading models (arbitrage, market making, refurbishment, regional, aggregation, asymmetry, consignment, distressed, virtual, synthetic, momentum) plus a rate-limit budget, in C and C++, joined to the advantage model; see its README | | `transport/` | Secure acquisition layer used by enrichment (see its README) | | `examples/` | Worked trade examples (illustrative data; see its README) | ## Build and run ```sh make # builds ./advantage (demo) and ./analyze make run # math demo make run-analyze # load + summarize advantages.xml make run-counsel # ranked counsel ``` ## XML additions ```xml held by default discounts trust until verified ``` The loader **fails closed** (exit 1, with the source named) on: a non-numeric or non-finite `reward`/`baseline`/`weight`, a negative weight, an assumption `status` other than `held`/`doubted`, a duplicate source `id`, or an `` outside ``, or a document that is cut short (a tag with no closing `>`, an unclosed element, or a missing ``) -- a partial store never passes for a complete one. Attribute names match whole (`xweight=` is not `weight=`; `uuid=` is not `id=`). The loader is also **bounded**: at most 16 MiB per document, 10,000 sources, and 100,000 observations per source. Beyond that it errors instead of consuming unbounded memory (see the `kMax*` constants in `advantage_store.hpp`). Attribute values must use double quotes. The observations shipped in `advantages.xml` are **illustrative seed data**, not measurements. Replace them with your own outcomes. ## How the score stays honest - `confidence = n / (n + prior)` (default prior 3): few observations earn little trust. - `trust` = held assumptions / total: doubted assumptions discount the score. - No evidence is **unknown, not zero**: scored 0 and flagged. - Spread larger than the average gain is flagged as inconsistent. - Overflowing evidence values withhold the score (0, flagged) rather than producing NaN. - Fetched (remote) lines are never used in scoring or advice; they are only counted, as untrusted. ## Enrichment safety (`analyze --enrich`) Off unless `--enrich` is given. Default schemes: `https` only. Hosts must be named with `--allow-host`. `file://` reads local files and is **not** covered by the host allowlist, so it needs the explicit `--allow-file`. Plaintext http needs `--allow-http` (discouraged).