Home /Modules/advantage/README.md

README.md

lib/advantage/README.md · 322 line(s) · markdown

artifact; pure; gasoline;

<!-- preonem: this document is an enacted artifact of the advantage legislature, graded unto time and space. See PREONEM.md. -->

Advantage™ — the SLeeLa library of advantage

Advantage™ is the SLeeLa standard-library family for advantaging a unique dividend with respect to a model. The name is a trademark of the SLeeLa project (MEARVK LLC). Where the toolchain prints its product identity to an interactive terminal, Advantage™ is rendered in the customary red (ANSI SGR 31, red + classic), the same treatment given to SLeeLa™ and Sleelvac™ — presentation-only and TTY-gated, so captured or piped output stays plain and machine-parsable.

Advantage™ turns a vague intuition — "work this to our advantage" — into a concrete, inspectable, testable process. At its heart is the Sequitur onion model: an ordered sequence of layers, wrapped like an onion around a value (the dividend), that you navigate inward toward the core and outward toward the skin, folding each layer's signed contribution into the running value. Over that spine sit five subject families — trade economics, trust-field physics, vertical integration, sophistication grading, and a routable output seam — each a self-contained, validated module with its own literature.

Documentation (the Advantage™ literature):

The Sequitur onion

"Sequitur" means it follows — each layer follows the previous in logical order. The layers form an onion, outer skin to inner core:

depthlayerkindrole
0dividendvaluethe value under consideration
1reviewvalidatelook again; confirm the premise
2concernsrisksurface risks and caveats
3mathsquantthe quantitative core
4additionsgrowwhat the layer adds to the dividend
5subtractionshrinkwhat the layer takes away
6regroupingreorgreorganize concepts; carry/borrow across the model
7iterationloopdecide to go further down or back up the onion

The Advantage™ subjects at a glance

Advantage™ is organized as a spine (the onion) plus eight subject families. Each subject is a directory of SLeeLa classes with a runnable demo and, for the two quantitative ones, a full prose treatment.

SubjectDirectoryWhat it advantagesLiterature
Onion model(root)a unique dividend, by a layered, navigable processthis README · DEFINITIONS.md
Trade economicsmath/a surplus shared between a buyer and a sellerMATH.md
Trust-field physicsphysics/trust as geometry — distance, curvature, decayPHYSICS.md
Vertical integrationintegration/a value chain, as recursively composable compartmentsDEFINITIONS.md §8
Sophistication gradinggrading/the ranking of modules and whole sets, A–DDEFINITIONS.md §9
Output seamoutput/where a module's own voice goesDEFINITIONS.md §10
Network tradesnetwork/buy/sell opportunities found and negotiated across a venue networkexamples/README.md
Connectivity mediumconnect/a uniform, fault-handled bridge to MySQL, national clocks, networks, and money sourcesconnect/README.md
Trading modelstrading/an asset position, across eleven models, ranked by evidence and trustTRADING.md

Read DEFINITIONS.md first for the vocabulary; then the subject documents for depth; then run the demos and primers to see each one prove itself.

Classes

FileClassPurpose
SLPackage.sleelaSLPackagePackage facade (compiler / Loader / Nordshrift)
SLAdvantageLayer.sleelaSLAdvantageLayerOne concentric onion layer (depth, name, kind, contribution)
SLAdvantageDividend.sleelaSLAdvantageDividendThe unique dividend held with respect to a named model
SLAdvantageSequitur.sleelaSLAdvantageSequiturThe ordered, navigable onion; cursor moves inward/outward; runs passes
SLAdvantageUserModel.sleelaSLAdvantageUserModelUser's model — simple, outcome-facing encapsulation
SLAdvantageDeveloperModel.sleelaSLAdvantageDeveloperModelDeveloper's model — full-control encapsulation of the process
advantage-demo.sleelaAdvantageDemoRunnable demo + validation of the onion model (main)
math/ (subfolder)—Bilateral trade economics subject — see below and MATH.md

math/ subfolder — trade economics subject

FileClassPurpose
math/SLJointProfitMax.sleelaSLJointProfitMaxJoint profit maximization — integrated surplus Π_total(Q) and Q* where MR = MC
math/SLNashBargaining.sleelaSLNashBargainingBilateral-monopoly Nash bargaining split by power index α over reservation profits
math/SLBilateralNewsvendor.sleelaSLBilateralNewsvendorOverage/underage costs on both ends + the centralized critical ratio
math/SLTradeMath.sleelaSLTradeMathSelf-contained expD / lnD / powAB / sqrtD helpers (no cross-package imports)
math/trade-math-demo.sleelaTradeMathDemoRunnable demo + validation of all three models (main)

Full definitions, explanations, ASCII sketches, and worked examples live in MATH.md.

physics/ subfolder — trust-field economics subject

A structural-economics subject that models trust and announcements as differential-geometry / contact-topology / stochastic objects (an analogy, flagged as such; the mathematics is implemented faithfully).

FileClassPurpose
physics/SLTrustMetric.sleelaSLTrustMetricTrust as a metric tensor g_μν; conformal warping of operational distance
physics/SLTransactionalGeodesic.sleelaSLTransactionalGeodesicChristoffel symbols + geodesic integration of the transaction path
physics/SLAnnouncementContact.sleelaSLAnnouncementContactContact 1-form α, the α∧dα≠0 test, hyperplane restriction, homotopy-null check
physics/SLTrustDecaySDE.sleelaSLTrustDecaySDECIR mean-reverting diffusion + Poisson jump (announcement breach)
physics/SLPhysicsMath.sleelaSLPhysicsMathSelf-contained expD/lnD/powAB/sqrtD (distinct name avoids collision)
physics/physics-demo.sleelaPhysicsDemoRunnable demo + validation of all four models (main)

Full definitions, explanations, ASCII sketches, and worked examples are in PHYSICS.md.

integration/ subfolder — vertical-integration subject

A sophisticated modelling option for vertical integration through capitalism / retail: a stack of value-chain tiers, each a recursively composable compartment with its own capacitive space, meaning, and relevance (OOD). Mainly a vertical arrangement (upstream → downstream); a tier may embed its own sub-model.

FileClassPurpose
integration/SLIntegrationKind.sleelaSLIntegrationKindCompartment-kind vocabulary: nested-model, onion, engineering-bay, trial, newton-tray, and plain holders (resources, mediums, hobbies, games, entertainment, processes, consumption, trading, gaining, selling, forcing, challenging)
integration/SLCompartment.sleelaSLCompartmentThe recursive, self-similar node (kind, capacitive space, meaning, relevance, child compartments)
integration/SLEngineeringBay.sleelaSLEngineeringBayMedium-capacity build/process compartment (load → build at a yield)
integration/SLTrialCompartment.sleelaSLTrialCompartmentStudy/experiment compartment (log trials, success rate)
integration/SLNewtonMedianTray.sleelaSLNewtonMedianTrayMedian-based enlightenment/insight tray
integration/SLVerticalIntegration.sleelaSLVerticalIntegrationThe ordered tier stack: vertical flow, recursion, aggregate capacity/relevance, system-sophistication score
integration/integration-demo.sleelaIntegrationDemoRunnable demo + validation (main)

Defined term-by-term in DEFINITIONS.md.

grading/ subfolder — sophistication circuit grader

A grader that scores each module and rates any set of modules — winning, losing, grader, and absolute sets — with letter + tier ratings.

FileClassPurpose
grading/SLModuleGrade.sleelaSLModuleGradeOne graded module: score → 1–10 tier + S/A/B/C/D/F letter; role (normal/grader/absolute)
grading/SLGradeSet.sleelaSLGradeSetA named set of modules with its own aggregate rating (mean/best/worst, set letter+tier)
grading/SLSophisticationCircuit.sleelaSLSophisticationCircuitThe circuit grader: register modules, apply win/lose/absolute thresholds, partition into sets, find the champion
grading/SLGradeBook.sleelaSLGradeBookTop-level: per-module & per-set ratings, overall field rating, win rate, rating of any supplied set
grading/grading-demo.sleelaGradingDemoRunnable demo + validation (main)

Defined term-by-term in DEFINITIONS.md.

output/ subfolder — output seam (terminal / CommonRails / socket)

So modules need not stay silent: a selectable output sink that routes rendered lines to the terminal, a CommonRails-formatted surface (via the toolchain's PrintRail), a socket/connector (framed + buffered for a native slnet_write), or a silent capture.

FileClassPurpose
output/SLAdvantageSink.sleelaSLAdvantageSinkThe sink: target (terminal/commonrails/socket/silent), endpoint, capture buffer, drain()/lastFrame()
output/SLAdvantageEmitter.sleelaSLAdvantageEmitterThe module-facing API (line, state, status, report, grade); formats via PrintRail for the CommonRails target
output/output-demo.sleelaOutputDemoRunnable demo + validation across all four targets (main)

The three top-level models (SLAdvantageDeveloperModel, SLVerticalIntegration, SLGradeBook) carry an emitThrough(emitter) method so they can report themselves to any target. Defined in DEFINITIONS.md.

trading/ subfolder — trading-models subject

Eleven cross-asset trading models, a rate budget, and counsel, ported from the C/C++ module in /advantage. Pure computation; every figure is validated by trading-demo against hand-computed anchors. See TRADING.md.

FileClassPurpose
trading/SLTradingResult.sleelaSLTradingResultCommon result plus the advantage bridge (baseline, advantage)
trading/SLTradingCheck.sleelaSLTradingCheckShared fail-closed validation and finite bounds
trading/SLTradingArbitrage.sleelaSLTradingArbitrageSame asset, two venues; break-even
trading/SLTradingMarketMaking.sleelaSLTradingMarketMakingQuote both sides; the unfilled case
trading/SLTradingRefurbishment.sleelaSLTradingRefurbishmentImprove and sell up-tier; outcome distribution
trading/SLTradingRegional.sleelaSLTradingRegionalMove it and sell elsewhere; loss and salvage
trading/SLTradingAggregation.sleelaSLTradingAggregationAssemble a set; completion probability
trading/SLTradingAsymmetry.sleelaSLTradingAsymmetryOne candidate: pay to look, win the race, be right
trading/SLTradingConsignment.sleelaSLTradingConsignmentCommission with no inventory
trading/SLTradingDistressed.sleelaSLTradingDistressedBuy from urgency; pursuit cost and remainder
trading/SLTradingVirtual.sleelaSLTradingVirtualSell before sourcing; fulfilment failure
trading/SLTradingSynthetic.sleelaSLTradingSyntheticOne into many or many into one
trading/SLTradingMomentum.sleelaSLTradingMomentumEvent-driven entry; exit failure; hype decay
trading/SLTradingRateBudget.sleelaSLTradingRateBudgetWait before the next request from rate-limit numbers
trading/SLTradingApproach.sleelaSLTradingApproachEvidence, assumptions, honest score
trading/SLTradingCounsel.sleelaSLTradingCounselRanks approaches best-first
trading/trading-demo.sleelaTradingDemoRunnable demo + validation (main)

The two models

Both operate on the same SLAdvantageSequitur + SLAdvantageDividend engine — the user's model is a thin, friendly skin over the developer's model.

Dynamically altering the model (to the owner's advantage)

The model can be re-shaped, re-pointed, and fully restored at runtime:

The demo's final sections exercise all of this: a baseline advantage of 10, favorOwner(4) raising it to 26 (shape gain +16), an updateModel onto a promo model, and a restitute that returns the model and advantage to their committed baseline.

Bilateral trade economics (math/ subject)

Math for advantaging a dividend across a buyer and a seller as one coordinated system, then dividing the surplus, now organized as the math/ subject: SLJointProfitMax (joint surplus + Q*), SLNashBargaining (the α-weighted split with a closed-form Nash price), and SLBilateralNewsvendor (overage/underage costs + the centralized critical ratio that avoids double marginalization). SLTradeMath supplies self-contained expD/lnD/powAB helpers so the subject needs no cross-package imports.

Full definitions, explanations, ASCII sketches, and worked examples are in MATH.md.

Run it

./working-binaries/sleela run lib/advantage/advantage-demo.sleela        # onion model
./working-binaries/sleela run lib/advantage/math/trade-math-demo.sleela  # trade math subject
./working-binaries/sleela run lib/advantage/physics/physics-demo.sleela  # trust-field subject
./working-binaries/sleela run lib/advantage/integration/integration-demo.sleela  # vertical integration
./working-binaries/sleela run lib/advantage/grading/grading-demo.sleela  # sophistication grader
./working-binaries/sleela run lib/advantage/output/output-demo.sleela  # output seam (terminal/rails/socket)

run auto-links the sibling classes in each directory (no imports needed). The onion demo validates the layered arithmetic (developer pass = 25, user advantage = 30). The trade-math demo validates every model against hand-computed anchors: Q* = 20, Π_total = 800, Nash price = 60 (400/400 split), critical ratio = 80/95 ≈ 0.8421.

Notes

Acknowledgments

With thanks to NC State University (NCSU), the University of North Carolina at Wilmington (UNCW), the University of North Carolina (UNC), and Duke University — the North Carolina research community whose teaching and scholarship inform the economics, geometry, stochastic-calculus, and software-design thinking behind the Advantage™ library. The library's models are the SLeeLa project's own constructions; the gratitude is for the education that made them possible, and no endorsement by any institution is implied.


Advantage™ — a trademark of the SLeeLa project, MEARVK LLC. Part of the SLeeLa™ standard library; built, checked, and run by Sleelvac™ / SLeeLa™ Language/Runtime 1.3.2-pro. Rendered in the customary red where the toolchain prints its product identity to a terminal. SLeeLa — MEARVK LLC — 2026.