docs

Author: tripolskypetr

docs/classes/ClientSimulator.md

@@ -10,22 +10,26 @@ Implements `ISimulator`
 Parameter sweep engine over crowd trading ideas (the "Simulator").
 
 Finds production strategy parameters (hard stop, trailing take,
-hold duration, entry consensus threshold) by simulating every idea
-against every point of the grid — WITHOUT re-running a backtest per
-point. The root iteration is over IDEAS, not candles and not grid
-points:
+hold duration, author ban rule) by simulating every idea against
+every point of the grid — WITHOUT re-running a backtest per point.
+Authors are graded STRICTLY in isolation — no interaction metrics
+(consensus counting, vote weighting) exist here by design; swarm
+ranking over long histories is userspace. The root iteration is
+over IDEAS, not candles and not grid points:
 
 1. Each idea gets ONE asynchronous forward candle pass from the
-   minute after its publication, capped by a static horizon
-   (IDEA_TRIM_DAYS). The pass produces a per-candle trajectory
-   profile (MFE/MAE extremes, whale shakeout depth, aligned-authors
-   count). Overlapping and sparse ideas are both supported: candle
-   chunks are fetched lazily through the Exchange (persist cache
-   first), gaps between ideas are never requested.
+   minute after its publication, capped by the grid's longest
+   hold (max of the holdMinutes axis — the schema defines the
+   horizon, not an engine constant). The pass produces a
+   per-candle trajectory
+   profile (MFE/MAE extremes, whale shakeout depth). Overlapping
+   and sparse ideas are both supported: candle chunks are fetched
+   lazily through the Exchange (persist cache first), gaps between
+   ideas are never requested.
 2. The author ban list is TRAINED on the whole range (lookahead
    inside train is deliberate): authors with enough ideas and a hit
-   rate worse than a coin are excluded from triggers and votes.
-   The list is part of the result — apply it in production as-is.
+   rate worse than a coin are excluded from entries. The list is
+   part of the result — apply it in production as-is.
 3. The outcome of every grid point is derived arithmetically from
    the profiles with production slot semantics (one position per
    symbol, busy-slot ideas skipped). Honesty contracts: entry at

docs/classes/MarkdownFileBase.md

@@ -60,20 +60,20 @@ _baseDir: string
 
 Base directory for all JSONL markdown files
 
-### __@WAIT_FOR_INIT_SYMBOL@5253
+### __@WAIT_FOR_INIT_SYMBOL@5257
 
 ```ts
-__@WAIT_FOR_INIT_SYMBOL@5253: (() => Promise<void>) & ISingleshotClearable<() => Promise<void>>
+__@WAIT_FOR_INIT_SYMBOL@5257: (() => Promise<void>) & ISingleshotClearable<() => Promise<void>>
 ```
 
 Singleshot initialization function that creates directory and stream.
 Protected by singleshot to ensure one-time execution.
 Sets up error handler that emits to exitEmitter.
 
-### __@WRITE_SAFE_SYMBOL@5254
+### __@WRITE_SAFE_SYMBOL@5258
 
 ```ts
-__@WRITE_SAFE_SYMBOL@5254: (line: string) => Promise<void | unique symbol>
+__@WRITE_SAFE_SYMBOL@5258: (line: string) => Promise<symbol | void>
 ```
 
 Timeout-protected write function with backpressure handling.

docs/classes/PersistBase.md

@@ -43,10 +43,10 @@ _directory: string
 
 Computed directory path for entity storage
 
-### __@BASE_WAIT_FOR_INIT_SYMBOL@4384
+### __@BASE_WAIT_FOR_INIT_SYMBOL@4388
 
 ```ts
-__@BASE_WAIT_FOR_INIT_SYMBOL@4384: (() => Promise<void>) & ISingleshotClearable<() => Promise<void>>
+__@BASE_WAIT_FOR_INIT_SYMBOL@4388: (() => Promise<void>) & ISingleshotClearable<() => Promise<void>>
 ```
 
 ## Methods

docs/classes/ReportBase.md

@@ -58,20 +58,20 @@ _stream: WriteStream
 
 WriteStream instance for append-only writes, null until initialized
 
-### __@WAIT_FOR_INIT_SYMBOL@5253
+### __@WAIT_FOR_INIT_SYMBOL@5257
 
 ```ts
-__@WAIT_FOR_INIT_SYMBOL@5253: (() => Promise<void>) & ISingleshotClearable<() => Promise<void>>
+__@WAIT_FOR_INIT_SYMBOL@5257: (() => Promise<void>) & ISingleshotClearable<() => Promise<void>>
 ```
 
 Singleshot initialization function that creates directory and stream.
 Protected by singleshot to ensure one-time execution.
 Sets up error handler that emits to exitEmitter.
 
-### __@WRITE_SAFE_SYMBOL@5254
+### __@WRITE_SAFE_SYMBOL@5258
 
 ```ts
-__@WRITE_SAFE_SYMBOL@5254: IWrappedQueuedFn<void | unique symbol, [line: string]>
+__@WRITE_SAFE_SYMBOL@5258: IWrappedQueuedFn<symbol | void, [line: string]>
 ```
 
 Timeout-protected write function with backpressure handling.

docs/classes/SimulatorUtils.md

@@ -26,32 +26,36 @@ Exit axes (always active in trade simulation):
 - holdMinutes — slot turnover cap; a busy slot absorbs qualified
   ideas (absorbedIdeaIds); time_expired is the worst-case exit.
 
-Entry gates (preprocessing of every candidate entry):
-- minIdeasAligned — unique UNBANNED aligned authors in the 4h
-  window; banned authors are invisible to the count.
-- minWeightAligned — sum of Laplace weights (hits+1)/(ideas+2) of
-  those authors; 0 disables the weighted gate.
+Entry gate (preprocessing of every candidate entry): any idea of
+an UNBANNED author triggers an entry. Authors are graded strictly
+in isolation — interaction metrics (consensus counting, vote
+weighting, Wilson bounds) do not exist here by design: swarm
+ranking over long histories is userspace.
 
 Ban rule (author filter, trained on the whole run range):
 - minAuthorTrack / minAuthorHitRate — default-ban thresholds;
   truncated profiles prove nothing; the ban is strictly below the
   rate threshold.
-- minAuthorWilson — minimum Wilson 95% lower bound of the hit
-  rate: proven quality that prices the track length in; 0
-  disables (pair-only baseline), and with the pair pinned inert
-  (track [0], rate [0]) the bound bans alone.
-- authorMetric — hit definition: "close" = 5-day horizon close
-  (lock/stop do NOT affect ban training), "reach" =
-  lock-reachability against the point's lock/stop; reach with
-  lock = 0 falls back to close.
-
-Run-level aggregation (not swept, ignored by test()):
-- banCriteria — which ranking winners feed result.allowedAuthors
-  (union) / bannedAuthors (banned by all); a winner elected by a
-  non-finite value (Infinity sortino/recovery) grants nothing.
-- reportOrder — ranking criterion ordering result.reports
-  (descending, tie-guarded comparator); default "sharpe". Purely
-  presentational: never affects winners, callbacks or ban lists.
+- authorMetric — hit definition, ALWAYS graded inside the point's
+  own hold window: "close" = window close (lock/stop do NOT
+  affect ban training), "reach" = lock-reachability against the
+  point's lock/stop, "retain" = fixation above the point's lock
+  (median move strictly above profitLockPercent), "pnl" = fixed
+  +1% MFE threshold, "trail" = arming reachability of the point's
+  trailing take; reach and retain require lock > 0, trail
+  requires trailing in (0, 100) — the inert combinations are
+  excluded from the grid.
+
+Run-level config (not swept, ignored by test()):
+- reportOrder — ranking criterion ordering each metric bucket's
+  reports (descending, tie-guarded comparator); default "sharpe".
+  Purely presentational: never affects winners or ban lists.
+
+The result is a per-metric dictionary: every swept authorMetric
+gets its own bucket with its own reports, its own four ranking
+winners and its own trained ban dictionaries (bans — one entry
+per unique rule, threshold arithmetic only). Nothing is ever
+aggregated across metrics.
 
 The simulator picks candidates — honest confirmation is a
 walk-forward test() shot, and the final arbiter for the chosen
@@ -92,11 +96,9 @@ default list; a single-value list freezes it), then every
 point of the cartesian product is evaluated arithmetically
 from the same profiles; see ISimulatorGridAxes for each axis'
 tune/ignore contract. Ranking winners honor the anti-fluke
-floor (a point below MIN_TRADES_FOR_BEST trades can win only
-when NO point clears the floor), and the run-level author
-lists aggregate ONLY the banCriteria winners with finite
-ranking values — an Infinity sortino/recovery winner grants
-no allowances.
+floor PER metric bucket (a point below MIN_TRADES_FOR_BEST
+trades can win only when NO point of its bucket clears the
+floor).
 
 ### test
 

docs/index.md

@@ -531,6 +531,8 @@ group: docs
 - [ISimulatorPointReport](interfaces/ISimulatorPointReport.md)
 - [ISimulatorAuthorStat](interfaces/ISimulatorAuthorStat.md)
 - [ISimulatorBest](interfaces/ISimulatorBest.md)
+- [ISimulatorRuleBans](interfaces/ISimulatorRuleBans.md)
+- [ISimulatorMetricReport](interfaces/ISimulatorMetricReport.md)
 - [ISimulatorResult](interfaces/ISimulatorResult.md)
 - [ISimulatorTestResult](interfaces/ISimulatorTestResult.md)
 - [ISimulatorSchema](interfaces/ISimulatorSchema.md)

docs/interfaces/ISimulatorAuthorStat.md

@@ -56,6 +56,5 @@ banned: boolean
 
 Author is banned under the ban rule these stats were computed
 with. True when the track is too short to judge (ideas <
-minAuthorTrack) OR the hit rate is below minAuthorHitRate OR the
-Wilson lower bound of the hit rate is below minAuthorWilson
-(when that bound is enabled). Unproven correctness = banned.
+minAuthorTrack) OR the hit rate is below minAuthorHitRate.
+Unproven correctness = banned.

docs/interfaces/ISimulatorBest.md

@@ -8,7 +8,7 @@ group: docs
 Winner of one ranking criterion with its trade list and the author
 artifact under ITS OWN ban rule. Different criteria may elect
 points with different ban rules — the whitelist is a property of
-the winning point, never a global of the run.
+the winning point, never a global of the run or the bucket.
 
 ## Properties
 
@@ -26,7 +26,7 @@ The ranking criterion this winner belongs to.
 report: ISimulatorPointReport
 ```
 
-Winning point report; null when the grid produced no reports.
+Winning point report; null when the bucket produced no reports.
 
 ### trades
 
@@ -42,12 +42,11 @@ Trades of the winning point (empty when report is null).
 authorStats: ISimulatorAuthorStat[]
 ```
 
-Per-author track records under THIS winner's rule — the ONLY
-source of the author artifact in a run result. Hits are counted
-by the rule's metric (authorMetric + the lock/stop levels the
-"reach" metric grades against), so even the raw numbers differ
-between winners with different rules — a single run-level list
-cannot represent them. Empty when report is null.
+Per-author track records under THIS winner's rule. Hits are
+counted by the rule's metric and levels, so even the raw
+numbers differ between winners with different rules. Empty when
+report is null. The same dictionary sits in the bucket's bans
+entry carrying the same thresholds/levels.
 
 ### allowedAuthors
 

docs/interfaces/ISimulatorCallbacks.md

@@ -62,8 +62,10 @@ One grid point evaluated.
 onRanking: (symbol: string, criterion: SimulatorRankingCriterion, sorted: ISimulatorPointReport[], best: ISimulatorBest) => void
 ```
 
-Ranking computed: reports sorted by the criterion (descending)
-and the eligible winner (minimum-trades filter applied).
+Ranking computed WITHIN one metric bucket: the bucket's reports
+sorted by the criterion (descending) and the eligible winner
+(minimum-trades floor applied per bucket). Fires once per
+(swept metric x criterion).
 
 ### onDone