Repository navigation
Trading Bot Model
📄 Canonical source:
docs/trading-bot-model.md
Status: Design intent (2026-09-02, user-confirmed direction). Canonical reference for the Trading Agent and any agent touching the automation/execution path. Supersedes the old "Trading Strategy = symbol-named strategy" mental model. Related: #674 (strategy redefinition), #624 (terminology — display-first), #574 (execution semantics), #714 (signal queues / single scoring line), #712 (protocol subscriptions).
A "strategy" is the whole pipeline — not the final wrapper.
The app is slowly moving away from a confused "Trading Strategies" area toward a clean separation:
| Layer | What it is | What it produces | Who owns it |
|---|---|---|---|
| Protocol | The signal thesis — which symbols/timeframes/directives, and a declared direction | BUY / HOLD / SELL signals per symbol | Signal engine (SEES) |
Trading Bot (a TradingStrategy DB row) |
The execution policy — money management, risk, entry/exit rules, position building, reserves | A queue head acted on, or a deliberate skip | The bot itself |
| Complete strategy | Protocol (signal source) + Bot (execution policy) | A trade, correctly sized and guarded | The pipeline |
Once a signal is produced it is queued to a specific bot; the bot decides whether to execute based on money/risk/position reality — it does not re-derive the signal.
Long and short are TWO ACTIVE STRATEGIES. A protocol declares a direction, so flipping the side makes a different strategy with its own protocol, its own bot and its own record.
Forbidden by construction: one bot trading both ways · one protocol scored both ways · any "both" / "either side" / "hedged" option inside a single run or a single bot. If a surface offers that, the surface is wrong — not the pipeline.
⚠️ This rule was decided long before 2026-11-01 and was written down NOWHERE. A search of the register,docs/, the roadmap data and the open issue tracker that day foundtrade both ways,both ways,long and shortandhedged modementioned zero times — so an agent re-derived the forbidden shape from scratch and shippeddirectionMode: "both"as a Backtest Lab option. An unrecorded rule is indistinguishable from no rule. Register row 113; guarded byrefuseUnrunnableDirection()(nest/src/modules/backtest/entry-side.ts), which the run path calls.To compare directions: run twice — once long, once short, same window — and compare the runs.
This is the most confusing thing in the codebase, and the §1 table above does not warn about it. Three separate Prisma models, all meaning something different, all named "strategy":
| Prisma model | Table | Rows | What it ACTUALLY is |
|---|---|---|---|
Strategy |
strategy |
37 | A named container: {name, description, version, config}. This is the "strategy" in the §1 sense — the idea, with its own name and id |
TradingStrategy |
trading_strategy |
40 |
A BOT. The execution policy. Named TradingStrategy because it predates this document |
ScoringStrategy |
scoring_strategy |
31 | Scoring + trade params for a protocol path (protocolId, watchlistName, tradeThreshold, gateConfig) |
⚠️ Row counts re-measured 2026-11-01 (previously stated 29 / 26 / 27 on 2026-09-18). They drift — every row is a protocol, a bot or a scoring path that someone added. Read them, do not quote them.strategyandtrading_strategyhave both grown faster thanscoring_strategy, so the three numbers moving together is not evidence that they are the same thing.
How it got this way. Strategy is the ORIGINAL top-level entity — it owns directives,
scores, signals and versions by relation. The META.Stack refactor moved directives under
Protocol (directive.strategyId is now 0 of 111 populated, re-measured 2026-11-01) and introduced TradingStrategy
for the execution layer. The old table was never retired, and the UI began calling the NEW rows
"strategies".
What still uses strategy. score.strategyId is 6479 of 6479 populated and joins
strategy.id (re-measured 2026-11-01; the 2026-09-18 figure was 4471 of 4494) — checked against
scoring_strategy.id, which matches 0. The scoring pipeline still writes scores against a strategy
row. directive.strategyId remains 0 of 111 populated, so the META.Stack move is complete on the
directive side and not on the score side.
Where the 37 rows come from — measured 2026-11-01:
| Kind | Count | Example name |
|---|---|---|
| Auto-generated, one per protocol | 36 | Signals Workbench — cac-speed-v1 |
| Hand-named | 1 | Conviction Dip Accumulation |
⚠️ The separator is an EM DASH (—, UTF-8E2 80 94), not an arrow. Verified withHEX(). This document previously wrote→, which means anyone grepping for the arrow finds zero rows and no error — the silent-empty-result failure this repo keeps re-finding. If you need to match generated names, matchSignals Workbench%, not the punctuation.
So the owner's question — "strategies ARE generated when certain other things are made?" — is
correct: a strategy row is created per protocol for scoring. That is why listing them feels
like listing protocols.
The single hand-named row is the shape §5's naming rule describes, and the shape a user would recognise:
name: Conviction Dip Accumulation
description: Soft long-only, share-buying. Accumulate on quality dips; hold through normal drawdown.
config: { "weights": {}, "entryThreshold": 60, "watchThreshold": 40, "defenseThreshold": 25 }
Rules for agents, until this is resolved:
-
A "bot" is a
trading_strategyrow. A "strategy" is astrategyrow. Different tables, different ideas. Say which you mean. -
TradingStrategyis a bot, despite the name. Do not treat the model name as evidence of what the row is. -
Two Trading-menu views are labelled "strategy" but render BOTS:
strategy-monitorandstrategy-comparison. Both read/api/trading/strategies//api/trading/strategy-comparison, i.e.trading_strategyrows. Renamed 2026-11-01 to Bot Monitor and Bot Comparison insrc/core/nav-tree.js.⚠️ This rule previously also listedstrategy-library, and that was WRONG. That page's primary query is/api/directives— it is a directive library that cross-references which bot runs each directive; renaming it "Trading Bots" would have been incorrect.trading-strategiesis no longer a nav entry at all. Verify a page's data source before renaming it on the strength of its id. -
NOT DECIDED: whether the auto-generated per-protocol
strategyrows should exist at all, or whether a strategy should only come into being when a human names one. Raise it; do not assume either answer.
"A strategy is about different treatment of a symbol." — the project owner
The rule, as given (corrected 2026-09-18 — this supersedes the earlier version):
"Two different bots results in two strategies." "Different markets. Is different configuration therefore the end result is a unique strategy." "The smallest change results in a different strategy because we cannot dismiss the power any single setting/behaviour could have on the stock market." "we should never have bots that do the exact same thing, even if it has different naming, it would mean its a duplicate and should be avoided"
- A strategy IS a bot's whole configuration: protocol + role + market + broker + execution policy.
- Any difference at all makes a different strategy. No field can be dismissed, however trivial the difference looks — that is the owner's explicit position.
- A different market IS a different configuration. Six bots on six FX pairs are six strategies.
- Two byte-identical bots are a DUPLICATE — a defect, not a merge. Such bots "should never" exist. The derivation does not fold them into one tidy row; it groups them (a stable key is what makes the fault detectable) and reports them.
Strategies = distinct full configurations. With no duplicates, that is one strategy per bot.
Measured 2026-09-18:
| Quantity | Value |
|---|---|
| Active protocols | 19 (11 with a bot, 8 with none) |
Bots (trading_strategy) |
26 |
| (protocol, bot) pairs | 26 = 25 subscriptions + 1 legacy-only |
| STRATEGIES | 26 — one per bot |
| Reachable (bot has a subscription) | 25 |
| Unreachable (#874 — bot with no subscription) | 1 |
| Duplicates | 0 (none exist — verified) |
forex-session-v1 strategies |
14 — one per market |
| Watchlists | 42 (26 linked to a protocol) |
An earlier version of this section said 15 strategies, then 18. Both were wrong. The errors are kept here because the shape of the mistake is the reusable part.
| Attempt | Said | Wrong because |
|---|---|---|
| 1st | 15 | the counting query omitted sessionWindow, even though the query that produced the raw rows had printed it (EURGBP … london, AUDUSD … asian) and the same run printed the with-session figure of 17, unused |
| 2nd | 18 | the identity excluded symbol, on the reasoning "symbols are scope, not identity". The owner corrected this: a different market is a different configuration |
| correct | 26 | every field contributes; identical bots are duplicates |
Both wrong answers had one shape: treating a field that happened to be UNCHANGED as though it
were not part of the identity. First sessionWindow was dropped from a count; then symbol was
dropped from the identity. The rule is now the opposite and simpler:
Every field contributes. If two bots differ in ANY field they are different strategies; if they differ in NO field they are duplicates, which is a defect.
The guard (nest/scripts/verify-strategy-derivation.ts) asserts all of these numbers, including the
canonicalisation rules, so neither error can recur silently.
signals-workbench is counted among the 8 boted-less protocols but is not a real trading
protocol (no trading style, no timeframe); it is the workbench container. Filter it before using
that number.
The gap. A MetaStack is defined in this codebase as **Watchlist + Protocol + Scoring Strategy
- Trading Strategy** (
stack-performance.service.tsL4,scoring.controller.tsL372) — but it has no identity.StackPerformanceService.computeAllRatings()iteratesscoring_strategyROWS, so one row = one "MetaStack". When several bots share a scoring strategy with different execution config, their results are blended into a single rating and you cannot tell which treatment works.
Measured 2026-09-18 — this is live, not hypothetical:
| Fact | Value |
|---|---|
trading_strategy rows sharing scoringStrategyId = auto-forex-session-v1
|
13 |
| Distinct execution treatments among those 13 | 6 |
Ratings GET /api/scoring/metastacks/ratings returns for them |
1 |
The six treatments are: six ungated 5m 0.01-lot bots, three london-gated, two asian-gated,
NZDJPY (0.1 lots — 10x), USDCAD (5-second timeframe), and USDJPY (1h, wider stops). One
blended rating currently covers all thirteen. That is the difference between listing rows and
listing strategies, stated as a measurement.
MetaStackSnapshot.fingerprint does not close this gap: computeFingerprint()
hashes fields from scoring_strategy only (protocolId, watchlistName, watchlistSymbols, brokerId, tradeThreshold, baseSize, slPct, tpPct, mode). Two bots with genuinely different
treatment on the same scoring strategy therefore produce the same fingerprint — the drift
detector is blind to exactly the difference that makes them different strategies.
The derivation rule.
A derived strategy is a distinct FULL configuration. The
strategyKeyis a stable SHA-256 over every part — it is the "ID along with the IDs of each part" the owner asked for. Two bots share a key only by being byte-identical, which is reported as a duplicate.
strategyKey = sha256( protocolId | role | symbol | brokerId | canonicalTreatment ) -> 16 hex
canonicalTreatment = { minComposite, baseSize, slPct, tpPct, maxHoldHours,
cooldownMinutes, maxPyramidTiers, timeframe,
sessionWindow, mode, maxPositions, maxDailyLoss,
useRaritySizing, maxSize }
symbol and brokerId are in the key on purpose. An earlier version excluded them as
"scope", which collapsed 26 strategies to 18. A different market is a different configuration.
sessionWindow is in the key on purpose. Omitting it is what produced the first wrong
answer (15).
Canonicalisation must be BEHAVIOURAL, not textual — two representations of the same configuration must hash identically, or bots that behave the same are reported as different strategies. Three rules, each verified by the guard:
| Rule | Why |
|---|---|
Numbers via toFixed(6)
|
1 and 1.0 must not hash differently |
| Keys emitted in sorted order |
JSON.stringify follows insertion order |
sessionWindow through parseSessionWindow()
|
Measured 2026-09-18: 9 bots store a bare london, 3 store ["london"]. Both are valid, the engine parses them identically, and the parser also folds aliases (sydney → asian, zurich → london). A hand-rolled second parser would drift from the one the engine actually uses |
null preserved explicitly |
NULL means "ungated" / "no limit" (#773) — a real state, not a blank and not 0 |
- Derived (no name) — computed on every read, never stored. Recomputed when a part changes, which is why a config edit replaces a key rather than mutating one.
- Pinned (named by the owner) — a name plus the part IDs recorded against the key, so the strategy survives a part being edited. This is the follow-up (#875) and is NOT built yet.
- Derivation is tracked by #876. Naming and full-pipeline backup are #875.
What this enables that does not exist today: a stable key to attach performance to, a surface
that shows 26 strategies rather than 26 anonymous rows or 27 blended ratings, and — later — a
snapshot/restore keyed on the STRATEGY rather than on scoringStrategyId (see #875).
Scope boundary. MetaStackVersioningService already snapshots and restores, and
MetaStackSnapshot (13 rows) already does the backup the owner described. It is keyed on
scoringStrategyId, so it covers 22 of 26 bots and collapses the FX fourteen into one. This is
widening an existing mechanism, not building a second one — see #875.
Verified by nest/scripts/verify-strategy-derivation.ts — 27 assertions driving the real
service against the real database, plus a canary that removes symbol from the identity and
confirms the guard fails (26 → 18, and 3 false duplicates detected).
Approach chosen: the signal locks the bot at enqueue time (Way 1).
- When
buildBestLadder()produces an actionable per-protocol record, the routing step assigns it to the applicable active bot (from the bot'sstrategy_protocolsubscriptions) and stores the bot on thestrategy_signal_queueentry. That entry now says: "execute THIS signal with THIS bot — no further routing checks." - The bot then performs its own checks on its queue head, every tick: "Do we have funds? Are we allowed to open a position now? Does my pacing/money rule allow it?" — which means the bot reads portfolio/positions data continuously.
- Capability-based assignment (the third approach, preferred for routing): the protocol declares what it needs (asset class, broker, trade style, direction) and the router picks the applicable bot from the pool at enqueue, then locks it. This supports many protocols → one bot and one symbol in two protocols → two different bots without hardcoding a 1:1.
Rule for agents: do not re-resolve "protocol → bot" at execution time (Way 2) — assignment happens once at enqueue and is locked. Do not reintroduce
compareProtocolPair/resolveBestSignal/evaluateStrategy(retired #714).
- Protocols today may not declare a clear trade type (stock vs CFD vs forex). Bots need to know which broker (and which broker type) a signal can be executed on — e.g. MT5 original vs Pepperstone MT5 differ in what they offer.
- This is handled at the edge: when a bot is bound to a protocol path, the binding must be broker/asset-aware. Many-protocols-to-one-bot makes this tractable — one bot per broker/asset family, subscribed to the relevant protocols.
For proving the model end-to-end we need bots with genuinely different behaviour:
- A CFD quick-win bot — serves a quick-win CFD protocol; takes profit without fuss; may run a faux trailing stop monitored by the app (not applied to the broker).
- A 4h / day-hold bot — serves a 4h protocol; holds through the day when the trend is strong.
Realistic shape (your NVDA example):
-
giantsprotocol = NVDA, GOOGLE, AMAZON → traded as CFD → a CFD bot. - A separate tech long-term protocol also includes NVDA → a stocks bot.
- NVDA can therefore appear twice in queue data, locked to two different bots, each path executable only by its own bot. That is expected and correct.
- A bot should be named by what it will do, not by its symbol(s):
Quick Win CFD,One-Buy Pyramid Investment(buys more once the prior entry is in profit and locked in),Multi-Buy Pyramid Investment(e.g. buy 5 symbols, then wait for one to go green before buying the next). - Display-first: change user-facing labels (Strategy Monitor, nav, Automation) to "Trading Bots" and behaviour-based names now; defer any code/DB identifier rename until later.
- The six "FX session" rows are really one or two behaviour-named bots (e.g.
Session FX — guarded) subscribed toforex-session-v1across symbol scopes — not six distinct "strategies."
- ❌ Reintroduce a second scoring line or strategy-side scoring (
evaluateStrategy). - ❌ Reintroduce the dual LONG-vs-SHORT winner-pick (
compareProtocolPair) — direction is the protocol's job; the bot does not compare two protocols. - ❌ Treat a
TradingStrategyrow as "a symbol pair to trade" — it is an execution policy. - ❌ Build a separate execution path for MANUAL trades — manual trades call the SAME execution library as the bot (sizing, stops, pyramid, cooldowns, trailing), configured by the #720 defaults when no bot matches. Decisions locked in #721.
- ✅ Keep the one-scoring-line + per-bot queue model documented in
automation-loop.service.ts.
The bot owns ALL trade-scenario functions — sizing, stop policy, pyramid/scale-in, cooldowns, trailing management. Manual trades (Signals cards) are just another caller of the same classes with the #720 default config. Two-layer stops, one rule everywhere:
- Broker-side protective stop — relaxed, always set on every position (initial AND follow-ups) so an app failure never leaves a position unprotected at the broker.
- App-managed trailing stop — tighter, adjusted by the app while it runs.
Pyramid/scale-in policy is the single TradingStrategy.maxPyramidTiers knob: 1 = one position
per symbol; >1 allows follow-ups when the existing position is green and its broker SL is
actually set at breakeven-or-better (mirrored for SHORT). See #721 and
docs/diagrams/manual-signal-trade-flow.md (Google Drive) for the full decision flow.
Execution feasibility is assessed twice with the same library (#723): once at signal GENERATION so the card shows execution blockers with change-hints before any click, and again at EXECUTION as the authoritative re-check. Every blocker carries a hint of what the user could change to reach a different outcome — no dead-end messages.
- #714 (queues / single scoring line) · #712 (protocol subscriptions) · #674 (redefinition epic) · #624 (terminology) · #574 (execution semantics) · #695 (FX go-live gate) · #721 (duplicate-position policy) · #720 (manual-trade defaults) · #719 (broker symbol availability).
Trading Command Suite · Financial Disclaimer · Installing · FAQ
Source · AGPL-3.0 · Issues · Discussions Built by Ryan Bayne · FifeCIC
💚 Support this project → — free, complete, no premium edition, and no income.
🛑 Not financial advice. The app ships unconfigured and is not set up to make money for you. Test on a demo account before connecting anything real.
v0.162.0 · alpha · © 2026 Ryan Bayne / FifeCIC · AGPL-3.0 · generated from the repository — corrections belong in the repo, not this page.
🛑 Financial Disclaimer — read before connecting an account.
🌐 Website · Screenshots
💚 Support this project — the app is free, complete, and has no income.
Start here
Understand
- How it works
- Glossary
- Scoring architecture
- Risk controls
- How a bot becomes a trade
- Screener contract
- Trading constraints
- Readiness tiers
- Notice codes
Help