Home /Modules/advantage/PROFITABILITY.SYSTEMS.INDEX.md

PROFITABILITY.SYSTEMS.INDEX.md

advantage/PROFITABILITY.SYSTEMS.INDEX.md · 265 line(s) · markdown

Profitability Systems Index

An index of every profitability-related model that genuinely exists in this repository: what it computes, where it lives, how it is checked, and — explicitly — what it does not compute. This document indexes code that is already written and tested. It does not introduce a new model or a new number.

Written precisely and without padding, on the premise that a careful reader deserves an accurate map rather than an impressive-sounding one.

1. Why this document exists, and a boundary it holds

A natural question after building several profitability models is: can one of them be scaled up — to a city, a population, a time horizon of years, a currency, a public office? This index answers that question directly: no, not as they stand, and not honestly. Every model below computes a bounded, specific quantity from caller-supplied inputs (a single trade's cost and proceeds, a position book's realized profit, a margin requirement). None of them estimates a population-wide or government-scale aggregate, a per-second income rate, or a flow of money to a named office such as a mayor. Composing several bounded, illustrative, single-trade models into a "profit per second to a city of 380,000" figure would not be a derivation — it would be an invented number wearing this repository's vocabulary. This index will not produce one. It instead gives, as accurately as the actual code allows, what each system is good for and where its scope ends.

2. Two implementations, one lineage

C/C++ coreSLeeLa port / native
single-trade evaluation§3.1 advantage/§3.2 lib/advantage/trading/
position books, margin— (not ported; SLeeLa-native)§4 lib/advantage/trading-actions-on-verb/
evidence + ranking§3.1 counsel.*§3.2 SLTradingCounsel
full model and lineage write-upSUPPORTED.MODELS.mdsame document, §6

This index is a map; SUPPORTED.MODELS.md is the canonical description of why each model exists and how it follows from the one before it. Where the two disagree, SUPPORTED.MODELS.md governs.

3. Single-trade evaluation (eleven models, one baseline, one ranking)

3.1 C/C++ core (advantage/)

Eleven models (trade_models.{c,h}, namespace by idea: arbitrage, market making, refurbishment, regional arbitrage, supply aggregation, informational asymmetry, consignment, distressed inventory, virtual inventory, synthetic bundling, event momentum) each evaluate one prospective trade into a common tm_result: total cost, expected proceeds, expected profit, return on cost, holding days. tm_baseline/tm_advantage turn a result into an advantage — reward above what capital would have earned otherwise — which addEvidence records into advantage_store (advantages.xml). counsel.* ranks recorded sources by mean advantage x confidence x trust and flags assumptions to verify first. rate_budget.* paces repeated reads against a server's own rate-limit headers; it never issues a request itself.

Computes: the expected profit of one trade, given inputs you supply, and a ranking of recorded approaches by historical evidence. Does not compute: a rate of income, a forecast, or anything about a geography or a population.

3.2 SLeeLa port (lib/advantage/trading/)

A 1:1 port of §3.1's eleven models plus SLTradingCounsel, validated by trading-demo (93 self-checks against the same hand-computed anchors as the C++ version; see TRADING.md). Same inputs, same tm_result shape (as SLTradingResult), same scope and the same limits.

3.3 Example tiers over the same models

lib/advantage/examples/{novice,medium,advanced,professional} and lib/advantage/medium-results/ apply §3.2's models to specific invented scenarios (a US small business, cross-venue commodity routing, a guardrailed first trade, twelve goods from lumber to smartphones). These are worked examples of the same bounded single-trade arithmetic, not a new model and not a scaled-up one; see EXAMPLES.md.

4. Position books, verbs and margin (lib/advantage/trading-actions-on-verb/)

A separate SLeeLa-native family (not a port of §3) that models an ongoing position — a sequence of buy/sell or short/cover actions over time — rather than one prospective trade. Full detail in SUPPORTED.MODELS.md §6 and in the folder's own README.md / ENGINEERING.md / ASSURANCE.md.

classcomputesdoes not compute
SLLongBookrealized profit of a long-only FIFO lot book; age/term queriesanything beyond the book's own recorded actions
SLShortBookthe mirror: short-only FIFO book, borrow cost, mark-to-marketa loss ceiling (none exists on the short side; see §6.2 of SUPPORTED.MODELS.md)
SLShortMarginequity, the ceiling-rounded margin requirement, a call amount, the fewest shares to cover, the first day a call falls dueany broker's or regulator's actual rule — the percentage is a caller-supplied parameter
SLEuclidgcd/lcm/Bezout, exact two-lot order fills, integer square root, nearest-target distance — the arithmetic the books above depend onanything about trading by itself
SLDailyCapBook (courseware)the same as SLLongBook, plus a fixed 2,000-actions-per-day teaching rulea real exchange's or regulator's throughput limit
SLDailyCapShortBook (courseware)the short-side mirror of SLDailyCapBook: SLShortBook's behavior plus the same 2,000-actions-per-day rulea real exchange's or regulator's throughput limit
SLBatchReturnthe exact total return over a stated batch of N trades (idealized win-rate/size inputs, or an explicit per-trade list), with no compounding, plus the exact per-trade average a stated total implieswhether any real trader achieves the stated inputs — see §6.1 below, in this document

SLLongBook, SLShortBook, SLShortMargin, SLEuclid and SLBatchReturn are checked by 27 use cases (test-suites/test-trading-actions.sh); SLDailyCapBook and SLDailyCapShortBook are checked separately by 20 courseware entries in long-medium-averages (test-suites/test-long-medium-averages.sh) — the two gates check disjoint classes, not the same seven classes twice. Both use the same methodology: self-checks, an independent Python oracle, differential tests against independent shadow implementations, and deliberately broken copies confirmed to fail the gate before being fixed. A later general code-quality review (not driven by any use case) found and fixed two real overflow bugs in SLBatchReturn itself — a magnitude-based rejection sentinel that could equal a real, legitimate large-batch loss, and a basis-point conversion that still overflowed after that fix — both confirmed genuine by reverting them and watching new boundary-case regression tests fail with the original symptom; see ASSURANCE.md's second review log.

4.1 Long-term potencies (lib/advantage/learner-vs-professional/courseware/long-term-potencies/)

A small courseware-only class, SLTermPotency, that defines a term not used anywhere else in this repository rather than letting it float free of a computed meaning. Two basis-point ratios, each read-only over an existing SLLongBook or SLShortBook (overloaded for both, resolved by argument type):

metricformulareads
term potency(units held/short that are long term) / (units held/short), in bpqtyLongTerm / totalQty or totalShort
age potencyweightedAgeFloor / oldestAge, in bpboth age queries, shared by either book

SLShortBook.isLongTerm/qtyLongTerm did not exist until this class needed them on the short side; they were added mirroring SLLongBook's wording and behavior exactly, and checked to produce identical readings to the long side at identical lot structure and ages (entry 5 of 6 in that folder) before being trusted. Checked by 6 entries (test-suites/test-long-term-potencies.sh): self-checks, an independent Python oracle (including ten randomly generated portfolios in entry 4), and the long/short cross-check above.

5. Grading, not payout: SLSophisticationCircuit (lib/advantage/grading/)

Worth naming explicitly because "grades" and "leading technician" appear in how this topic has been discussed. SLGradeBook, SLModuleGrade, SLGradeSet and SLSophisticationCircuit grade the sophistication of a software module (a 1–10 tier and an S/A/B/C/D/F letter, derived from a raw score the caller supplies) and can group graded modules into a named, aggregately-rated set (SLGradeSet: winning, losing, grader or absolute modules), for use inside this library's own self-grading demos. This is a code-quality rubric, not a trader-skill tier and not a payout schedule. It has no relationship to a "Grade 1–5 trading technician" acting on a city's behalf; no such construct exists in this codebase.

6. Why a city, a mayor, or a multi-year/multi-currency extrapolation is out of scope

Stated plainly, because an index that silently omits a question invites the reader to assume an answer exists elsewhere. It does not. Specifically:

If a real question sits behind this — for instance, "how would one scale a specific, named trading strategy's expected return given a specific capital base and a specific time horizon" — that is answerable with §3's existing tools (supply real inputs to a specific model, read the tm_result, and report the single-trade answer honestly scaled by the capital actually deployed). It is not answerable by assuming a city's population, a mayor's share, or a multi-decade compounding rate, because none of those quantities exist anywhere in this codebase's inputs.

6.1 SLBatchReturn: a real answer to "what would N trades return"

Built to replace an unverified claim with a checked computation. Given stated inputs — either an idealized win-rate and per-trade win/loss size, or an explicit list of per-trade percent moves (up to 64) — it computes the exact batch total, in basis points, with no compounding (every trade re-stakes the same capital, modeling N independent fixed-size trades). It also computes the exact per-trade average a stated total implies (averagePerTradeBp), and cross-checks an explicit batch against real SLLongBook buy/sell pairs (crossCheckOutcome), distinguishing "the sums matched" from "a trade could not be represented" (for example a -100% move, which SLLongBook correctly refuses as a zero-cent sell price) from a genuine mismatch. See use case 27 (27-batch-return/TaUse27BatchReturn.sleela) and reading/ages-18-plus/07-batch-vs-per-trade.md. It computes what a stated assumption implies; it does not and cannot confirm the assumption is true of any real trader.

6.2 The estimated-return table that was asked for, and why it stops at one trade

A chart of hypothetical trading percentages was requested during planning: a trader's "good day" return of 2% to 17%, and a "microtrade advantage" multiplier of 2x up to 12x or more. It is included here, computed exactly with the real SLLongBook for one invented trade of $10,000 (1,000,000 cents), because the arithmetic itself is the useful part — not because the percentages are realistic.

return assumed on one tradesell price (cents, from a 100-cent buy)profit (cents)capital afterward, as a multiple
2% ("a good day," low end, as given)10220,0001.02x
5% ("a good day," mid)10550,0001.05x
10% ("a good day," high-ish)110100,0001.10x
17% ("a good day," high end, as given)117170,0001.17x
100% ("microtrade advantage," 2x)2001,000,0002.00x
300% ("microtrade advantage," 4x)4003,000,0004.00x
1,100% ("microtrade advantage," 12x)1,20011,000,00012.00x

No row is estimated by a model; each is profit = capital x return% for one stand-alone trade, with no repetition and no compounding. "Estimated" here means assumed as a hypothesis to test, not derived from evidence. No naming scheme (for example "Status I" or "Convenient II") is attached to this table: that terminology could not be verified as established usage, and real, unrelated academic terms that sound similar (the "convenience yield" / reserve-currency "status" of a safe asset, in the Treasury-bond literature) measure a safety-and-liquidity premium, not a trader's return, so borrowing either name here would misstate what the table is.

Why this does not become a daily rate, a yearly rate, or anything bigger: compounding any of these percentages across trading days shows the assumption breaks down almost immediately — 2% a day compounds to about 1,377x in one year, and 17% a day compounds to over 100x in 30 trading days, both figures outside what any real market or strategy sustains. The full compounding table, independently cross-checked, and the reasoning behind it are in reader 6 of the adult courseware. This is also why §6's refusal to extrapolate to a city, a mayor, a currency or a decade stands: the per-trade numbers above are already shown, by direct computation, not to survive being repeated — so there is no sustainable rate left to extrapolate in the first place.

7. Reading paths