Home /Modules/advantage/SUPPORTED.MODELS.md

SUPPORTED.MODELS.md

advantage/SUPPORTED.MODELS.md · 421 line(s) · markdown

Supported Models

Every model this module supports, what it does, and why it follows from the one before it (sequitur: each model exists because the previous one left a question open).

All models are pure computation in C with a C++ layer. None of them fetches prices, scrapes anything, or places an order. Callers supply the inputs; the models return an evaluation.


1. The Foundation: the Advantage Model

1.1 Advantage (the math core)

advantage.h: advantage_value, advantage_mean, advantage_stddev, advantage_confidence.

An advantage is what you gained (reward) beyond what you would have gained anyway (baseline), scaled by a weight. Alongside it are two honesty measures: spread (how consistent the gains are) and confidence (n / (n + prior), so a few results earn little trust).

Why it comes first: every other model is, at bottom, a way of estimating a reward against a baseline. Without a single definition of "better than otherwise," the models cannot be compared.

1.2 The knowledge store

advantages.xml, advantage_store.*.

Holds source advantages: kinds of leverage, each with the assumptions it depends on, short knowledge strings, and recorded evidence (<observation reward baseline/>). The five shipped sources are Source/Spring, Mechanical Advantage, Genius, Kid and Simple Money. An assumption can be marked status="doubted".

Why it follows the math core: a number means little without the beliefs that produce it. The store keeps those beliefs next to the evidence, and keeps authored knowledge separate from fetched (untrusted) text.

The loader fails closed on malformed numbers, truncated documents, duplicate ids and stray elements, and is bounded (16 MiB, 10,000 sources, 100,000 observations per source).

1.3 Counsel

counsel.*, run with analyze --counsel.

Ranks sources by score = mean advantage × confidence × trust, where trust is the share of the source's assumptions still held. It also lists what to verify first (doubted assumptions first) and states plain-language cautions.

Why it follows the store: the store holds evidence and assumptions; counsel turns them into a decision without claiming more than the evidence supports. No evidence is reported as unknown, not zero.

1.4 The bridge: trades become evidence

tm_baseline, tm_advantage, addEvidence (C++).

An evaluated trade is expressed as reward = expected proceeds against baseline = total cost plus the opportunity cost of the capital tied up for the holding time. addEvidence records it as an observation. With Scale::PerUnitCost the reward and baseline are divided by total cost, so a $20,000 token trade and a $100 dresser flip compare per unit of capital rather than by size.

Why it matters: this is what makes the trading models part of one system rather than a list. Each model below ends in the same place: a tm_result that counsel can rank.


2. The Trading Models

All eleven share one result shape (tm_result: total cost, expected proceeds, expected profit, return on cost, hold days) and one set of conventions:

The models are grouped below by the question each one answers, in the order they build on one another.

A. Where does the edge come from? (price, quote, transformation)

2.1 Arbitrage: tm_arbitrage, tm_arbitrage_breakeven

Idea: the same asset trades at two prices on two venues; buy low, sell high. Digital: a token bought on a DEX and sold on a CEX. Physical: a regional listing relisted on a premium venue. Captures: both-leg fees, slippage, fixed costs, holding cost, and time. tm_arbitrage_breakeven gives the lowest sell price that breaks even. Why it is first: it is the simplest possible edge, a visible price gap, and it establishes the cost vocabulary (fees, slippage, holding) every later model reuses.

2.2 Market making: tm_quote, tm_marketmaking

Idea: instead of waiting for a gap, create one by quoting both sides and earning the spread. Digital: order-book or AMM quoting. Physical: buying estate lots for cash, reselling at market. Captures: the unfilled case: inventory that does not turn over is dumped at an unwind loss. A negative fee models a maker rebate. Why it follows arbitrage: arbitrage needs someone else's mispricing; market making manufactures the spread, which introduces the first genuinely new risk, inventory that does not sell.

2.3 Refurbishment: tm_refurbishment

Idea: buy raw or distressed, improve it, sell into a higher tier. Digital: raw coins sent for professional grading. Physical: restoring mid-century furniture. Captures: the result is a distribution of outcomes (a list of probability / value branches that must sum to 1), not a single number. Why it follows market making: the edge here is created by work, not by a quote. Because work can come out several ways, the model needs outcome distributions, a structure later models reuse.

B. What if the edge is in space, in pieces, or in what others miss?

2.4 Regional arbitrage: tm_regional, tm_regional_premium

Idea: buy in one place, move it, sell in another. Digital: a country-exclusive premium held up by capital controls. Physical: estate-sale furniture sold in a dense urban market. Captures: transport cost per unit, transit time, and the chance the move fails or damages the goods, with a salvage rate. Why it follows arbitrage: it is arbitrage where "the other venue" is far away. Moving is itself a risky step, so loss and salvage become inputs.

2.5 Supply aggregation: tm_aggregation

Idea: collect many small items from fragmented sellers into a cohesive set and sell the set at a premium. Digital: sorted, attributed coin sets. Physical: matched dining chairs. Captures: completion probability. An incomplete set sells for little more than its parts. Takes up to 256 individual lot prices. Why it follows refurbishment: value is created by assembly instead of repair, and the new risk is that the assembly never finishes.

2.6 Informational asymmetry: tm_asymmetry, tm_mispricing

Idea: a listing is mislabeled, mispriced or misunderstood. Digital: mispriced listings and panic discounts. Physical: "old wooden table" that is a designer piece. Captures: one evaluation is one candidate. You pay to look every time, buy only if you win the race against other buyers, and profit only if your read of it was right. This is why "bots win most races" comes out as a loss. Why it follows the previous two: aggregation and regional arbitrage work when the gap is visible; here the gap is hidden, so the model has to price the cost of searching, not just the trade.

C. What if you remove capital, or exploit someone's urgency?

2.7 Consignment / zero inventory: tm_consignment

Idea: match buyers and sellers for a commission; hold no inventory. Digital: a local OTC or escrow desk. Physical: staging and selling for people moving out. Captures: almost no capital, so return on cost can look enormous. The real inputs are your labor and counterparty risk (a chargeback or reversal), both explicit. Why it follows asymmetry: after paying to search and compete, the natural question is whether you can earn without owning anything. The honest answer is that you swap capital risk for trust risk.

2.8 Distressed inventory: tm_distressed

Idea: buy from sellers who value speed and certainty over price. Digital: assets dumped by forced liquidations into a thin book. Physical: office-mover, eviction or storage-auction truckloads. Captures: a win probability against institutional liquidators, a cost to pursue every lot, the sell-through rate, and what it costs to dispose of the rest. Why it follows consignment: consignment serves a seller who wants help; distressed buying serves a seller who wants to be gone. It reuses the race-and-pursuit structure from asymmetry and the unsold-remainder idea from market making.

2.9 Virtual inventory: tm_virtual

Idea: take the customer's payment first, source the item after. Digital: dealer-fulfilled graded coins. Physical: resale of standard items collected after the buyer has paid. Captures: source price drift between sale and purchase and the probability you cannot fulfil, with the loss when that happens. Return on cost here is on total outlay, not your own capital, so the failure probability is the number to stress. Why it follows distressed: distressed buying commits capital early; virtual inventory reorders the steps so the sale funds the purchase. It is the logical extreme of capital efficiency, and its price is fulfilment risk. It assumes an honest, disclosed sale.

D. What if you can change the thing itself, or the clock is the edge?

2.10 Synthetic bundling: tm_synthetic

Idea: turn one thing into many, or many into one. Digital: wrap/unwrap spreads; breaking up a coin estate into collector pieces and melt value. Physical: assembling salvaged parts into a bespoke piece. Captures: input cost, transform cost per output, waste, and a fallback value (for example melt) for outputs that do not sell. Up to 64 outputs. Why it follows virtual inventory: it generalizes refurbishment (one in, one better out) and aggregation (many in, one out) into a single structure that also covers the reverse (one in, many out).

2.11 Event momentum: tm_momentum, tm_hype_decay

Idea: enter on a news or trend shock and exit while demand is elevated. Digital: newly listed or newly newsworthy tokens. Physical: vintage pieces in a style that is going viral. Captures: an exit-price distribution, the probability of being unable to exit at all (often with near-zero recovery), and a half-life for how fast hype decays. Why it comes last: every earlier model has an edge that persists for the holding period. This is the one where time itself is the edge and the risk, and it extends the "inventory that does not sell" idea from market making into a first-class exit-failure probability. It treats inability to exit as a first-class outcome. In thin markets you can be the exit liquidity for someone else's promotion; the numbers here are not a reason to promote a token you hold.


3. Supporting Model: the Rate Budget

rate_budget.h: rb_parse_nonneg, rb_observe, rb_next_delay_ms (C++: RateBudget).

Reads X-RateLimit-Limit, -Remaining, -Reset and Retry-After and returns how long to wait before the next request: the usable budget (remaining minus a reserve) spread evenly over the time left in the window, never below a minimum interval, and an explicit Retry-After always wins. A required wait above the caller's cap returns "stop." Malformed headers are rejected and leave the state unchanged. It never sleeps and never makes a request.

Why it is sequitur: the models that depend on fast-moving data (asymmetry, distressed, momentum) are exactly the ones tempted to read faster than a server allows. The rate budget is the discipline that lets them read as fast as is permitted, and no faster.


4. How They Fit Together

 inputs you supply (prices, fees, odds, days)
        |
        v
 one of 11 trading models  --->  tm_result (cost, expected proceeds, profit)
        |
        v
 tm_baseline / tm_advantage  (adds opportunity cost of capital)
        |
        v
 addEvidence  --->  AdvantageStore (observations; assumptions held/doubted)
        |
        v
 counsel:  score = mean advantage x confidence x trust
        |
        v
 ranked approaches, with what to verify first and why to be careful

The progression by axis, for orientation:

AxisModels
Price gapArbitrage, Regional arbitrage
Created spreadMarket making
TransformationRefurbishment, Aggregation, Synthetic bundling
Hidden informationInformational asymmetry
Seller urgencyDistressed inventory
Capital structureConsignment, Virtual inventory
TimeEvent momentum

A reading, not a derivation: the five shipped source advantages are general kinds of leverage, and the trading models are concrete, quantified instances of the same idea (insight pays off in asymmetry, liquidity in market making and consignment, leverage from position in regional arbitrage).


5. Limits That Apply to Every Model

Deliberately not built

SLeeLa port

All eleven models, the rate budget, and counsel are ported to SLeeLa in lib/advantage/trading/ (see lib/advantage/TRADING.md). The port is validated by a runnable demo of 93 self-checks against the same hand-computed anchors, and matches this module's counsel scores. One honest difference: the SLeeLa String type has no character access, so the rate budget there takes already-parsed numbers instead of header text.

Planned


6. SLeeLa-Native Position and Margin Models (lib/advantage)

A separate, newer family of SLeeLa-native models, distinct from the eleven trading models above and from their 1:1 port. Where the models in sections 1-2 evaluate a single prospective trade against a baseline, this family models an ongoing position book: a sequence of buy/sell (or short/cover) actions over time, with exact FIFO lot accounting, and the margin arithmetic a short position needs. They share this module's conventions (fail closed, finite bounds, illustrative data only, no execution) but use verbs and status codes rather than a tm_result/evidence/counsel pipeline, so they are documented here as their own family rather than folded into the eleven above.

Location: lib/advantage/trading-actions-on-verb/ (engineering detail: ENGINEERING.md, checking: ASSURANCE.md). Companion courseware: lib/advantage/learner-vs-professional/.

6.1 Long position book: SLLongBook

A long-only FIFO lot book with four verbs: buy, sell (oldest lot first), hold (let time pass) and flatten (sell everything held). A sell larger than the holding is refused (status 3) and never becomes a short; every refusal leaves the book unchanged. Tracks realized gross/net profit (net is a cash view: proceeds minus cost sold minus every fee paid), and time-on-long queries (age, FIFO-aware weighted average age, a strict "more than N days" term boundary, and the shares held past an age limit for a time-stop loop). invariantsHold() checks conservation of shares and cost after every action.

6.2 Short position book: SLShortBook

The mirror of SLLongBook: shortSell, cover (oldest lot first), hold, coverAll. Short only (a cover above the shares short is refused, status 3, never becomes a long). Adds a borrow cost (cents per share per day, frozen while any share is short) and markToMarket. The mirror law: given the same days, quantities, prices and fees, every status code, share/lot counts, ages and cost-basis-versus-proceeds match the long book, and short realized gross is exactly the negative of long realized gross — checked over 1,200 random actions per run (use case 22) against the long book itself, and separately against an independent per-share shadow model (use case 21).

6.3 Short margin: SLShortMargin

Illustrative margin arithmetic, explicitly not a broker or regulator rule: the required percentage is a caller-supplied basis-points parameter. Computes equity (collateral minus short value), the required margin as an exact ceiling of value times percent (computed without ever forming a product that could exceed the runtime's exact-integer-comparison limit), the deposit that clears a call, the fewest shares to cover to clear a call (binary search, checked against a linear scan and for minimality — and against a negative- equity case where no cover can help), and the first day a call becomes due under ongoing borrow cost (closed form, checked against day-by-day stepping).

6.4 Careful integer toolkit: SLEuclid

Supporting integer routines built for this family and reused by it: gcd, gcdAll, lcm, extended Euclid (egcd, with a Bezout-identity check), exact two-lot-size order fills in logarithmic time (canFill, with a linear canFillScan kept as a reference), an exact integer square root (isqrt), and squared Euclidean distance / nearest-target selection (distSq, dist, nearestIndex). Every routine states its loop invariant and termination argument, and every bound is sized against the runtime's measured integer-comparison exactness limit (exact only up to 2^53 - 1, not the full 64-bit range) rather than assumed; out-of-range input is refused, never silently clamped or wrapped.

6.5 Daily action cap: SLDailyCapBook

A teaching variant of SLLongBook (in the courseware, not the core trading folder) with one added rule: a single day may record at most 2,000 actions across buy/sell/hold/flatten; the 2,001st is refused (status 10) and changes nothing, and the count resets when the day changes. This is a fixed teaching bound, not a market or regulatory limit.

Checking

26 use cases exercise 6.1-6.4 (test-suites/test-trading-actions.sh); 17 courseware entries exercise 6.5 (test-suites/test-long-medium-averages.sh). Expected values for the deterministic cases were independently computed in Python and compared against the SLeeLa output; the random/differential cases (6.1-6.2 mirror and shadow tests) were cross-checked the same way. Several deliberately broken copies of these classes (an off-by-one in a rounding step, a sign flip, an allowed-one-too-many bound, a non-terminating search) were each confirmed to make the gate fail before the fix was accepted.

Honest limits of this family