nexustrade 1.52.0 → 1.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -7,9 +7,11 @@ friendlier read.
7
7
  ## What this package is
8
8
 
9
9
  A typed client plus ~170 **generated** builders for authoring trading
10
- strategies. The builders are generated from the same indicator specification the
11
- NexusTrade engine executes, so a book assembled from them is structurally valid
12
- before it ever leaves the process.
10
+ strategies. The builders are generated from the engine's indicator specification.
11
+ They describe draft payloads; the API still validates complete portfolios and
12
+ their conditions. A builder's existence does not guarantee support for every
13
+ trading method. Read the [option selection and execution limits](README.md#option-selection-and-execution-limits)
14
+ before claiming exact option timing, expiration selection, or rolling behavior.
13
15
 
14
16
  ```
15
17
  author a portfolio → submit a job → poll until terminal → read result
package/README.md CHANGED
@@ -234,6 +234,36 @@ nt.strategy("Sell the credit spread for the debit fill plus $0.50", whenDebitSpr
234
234
  It keeps the no-worse-than-current-quote protection, but it is not a resting
235
235
  price target. Live option strategies must choose an explicit Limit policy.
236
236
 
237
+ ### Option selection and execution limits
238
+
239
+ Builders describe drafts. Typechecking does not prove that the engine can
240
+ execute every requested rule; the API validates complete portfolios and their
241
+ conditions.
242
+
243
+ - Expiration selectors support a DTE window and `nearest`, `middle`, or
244
+ `furthest`. `middle` selects the middle eligible expiration by index, not the
245
+ expiration nearest a target such as 180 days. There is no monthly-only or
246
+ quarterly-only expiration filter.
247
+ - `rebalanceOption` accepts `renewBeforeDays` (integer 1–90) and
248
+ `revisitDisclosedTargets`. These maintain modeled political-disclosure option
249
+ targets. The strategy must contain a `NewPoliticalDisclosure` condition for
250
+ instrument `Option` with exactly one member ID. These fields do not implement
251
+ a general close-and-replace roll for a trend strategy.
252
+ - For backtests, the job's `feeConfig.OptionSlippageFraction` sets quote-side
253
+ fills: `0` uses the midpoint, `1` uses ask for buys and bid for sells, and the
254
+ default is `0.5`. This job setting does not add a last-trade fallback or define
255
+ live order execution.
256
+ - Evaluation timing and order execution are separate. `OpenClose` schedules
257
+ evaluations at session open and close; it does not itself carry a signal
258
+ observed at close into an order at the next open. Explicit zero timing offsets
259
+ and a `gt(MinutesAfterOpen(), Value(0))` condition can restrict evaluations
260
+ to the calendar session close. `MinutesUntilClose` counts down to 16:00 Eastern,
261
+ so it cannot identify an early session close.
262
+
263
+ When authoring an approximation, describe the actual expiration policy, signal
264
+ timing, fills, and replacement behavior. Backtest results describe that
265
+ implementation, not the exact method it approximates.
266
+
237
267
  <details>
238
268
  <summary><b>What you can build</b> — 170+ generated builders</summary>
239
269
 
@@ -680,14 +680,16 @@ function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
680
680
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
681
681
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
682
682
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
683
+ * @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
683
684
  */
684
- function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0) {
685
+ function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
685
686
  const d = { type: "ChartBar" };
686
687
  setAsset(d, "targetAsset", asset);
687
688
  d["barMinutes"] = barMinutes;
688
689
  d["line"] = line;
689
690
  d["bars"] = bars;
690
691
  d["offsetBars"] = offsetBars;
692
+ d["minutePolicy"] = minutePolicy;
691
693
  return d;
692
694
  }
693
695
  /**
@@ -430,9 +430,9 @@ export interface RebalanceOptionAction {
430
430
  sleeves?: RebalanceOptionSleeve[];
431
431
  allocationPolicy?: AllocationPolicy;
432
432
  exposurePolicy?: ExposurePolicy;
433
- /** Simulated option replacement before modeled expiry when no full sale was disclosed. */
433
+ /** Disclosure maintenance only: requires a NewPoliticalDisclosure Option condition with exactly one memberId; integer 1..90. Not a generic DTE roll. */
434
434
  renewBeforeDays?: number;
435
- /** Revisit continuing public option targets only when another option filing arrives. */
435
+ /** Disclosure maintenance only: revisit continuing public option targets when another option filing arrives. Same condition restriction as renewBeforeDays. */
436
436
  revisitDisclosedTargets?: boolean;
437
437
  }
438
438
  export type OptionParentSelectionSort = "oldest" | "highestPnl" | "nearestExpiry";
@@ -775,20 +775,7 @@ export declare const sleeve: (config: {
775
775
  * Rank a universe and rotate an option book. Keep take-profit / stop-loss / DTE
776
776
  * exits in separate closeOption strategies, not here.
777
777
  */
778
- export declare const rebalanceOption: (config: {
779
- universe: Universe;
780
- pipeline: PipelineStage[];
781
- weightIndicator: Indicator | CandidateIndicator;
782
- structureTemplates: OptionStructureTemplate[];
783
- limit?: number;
784
- totalBudget?: DeploymentBudget;
785
- perNameAllocation?: OptionAllocation;
786
- sizingMode?: "fixedPerName" | "proportionalToWeight" | "proportionalToWeightWholeContracts";
787
- positionScope?: RebalanceOptionPositionScope;
788
- sleeves?: RebalanceOptionSleeve[];
789
- allocationPolicy?: AllocationPolicy;
790
- exposurePolicy?: ExposurePolicy;
791
- }) => RebalanceOptionAction;
778
+ export declare const rebalanceOption: (config: Omit<RebalanceOptionAction, "type">) => RebalanceOptionAction;
792
779
  export declare const pnlTrigger: (bounds: {
793
780
  minPnlPercent?: number;
794
781
  maxPnlPercent?: number;
@@ -919,8 +906,9 @@ export declare function ChaikinMoneyFlow(asset: AssetArg, length?: number, inter
919
906
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
920
907
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
921
908
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
909
+ * @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
922
910
  */
923
- export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number): Indicator;
911
+ export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number, minutePolicy?: "strict" | "observed"): Indicator;
924
912
  /**
925
913
  * CommodityChannelIndex indicator.
926
914
  * @param asset Ticker name (ex. SPY, BTC)
@@ -1753,7 +1741,7 @@ export interface FeeConfig {
1753
1741
  Stock?: FeeAmount;
1754
1742
  Cryptocurrency?: FeeAmount;
1755
1743
  Option?: FeeAmount;
1756
- /** Rust-owned option fill slippage; absent means the engine's 0.5 default. */
1744
+ /** Option fill slippage: 0=quote mid, 1=ask for buys/bid for sells; absent means 0.5. Requires a current executable quote. */
1757
1745
  OptionSlippageFraction?: number;
1758
1746
  }
1759
1747
  export interface MetricConstraint {
@@ -1800,7 +1788,7 @@ export interface BacktestConfig {
1800
1788
  initialValue?: number;
1801
1789
  /** Generate detailed event data (signals, orders, audits) during backtest. Costs 5x research tokens. Events are Mongo hot-store traces retained for 3 days. Use query_backtest_events to explore them while retained. */
1802
1790
  generateEvents?: boolean;
1803
- /** Optional fee contract keyed by AssetTypeEnum (Stock/Cryptocurrency/Option) with {amount, type: percent|dollars}. Omit for shared defaults (Option $0.65/contract). For replay of an optimizer/walk-forward study, pass that study's persisted feeConfig. Option fill slippage (OptionSlippageFraction) is not set here — engine default 0.5 applies. */
1791
+ /** Optional fee contract keyed by AssetTypeEnum (Stock/Cryptocurrency/Option) with {amount, type: percent|dollars}. Omit for shared defaults (Option $0.65/contract). For replay of an optimizer/walk-forward study, pass that study's persisted feeConfig. OptionSlippageFraction is supported: 0 fills at quote mid, 1 at ask for buys/bid for sells; omitted uses the engine default 0.5. Fills require a current executable quote; this does not enable last-trade fallback pricing. */
1804
1792
  feeConfig?: FeeConfig;
1805
1793
  /** Overrides the portfolio's dividend policy for this run only. Omit to use the portfolio's own setting (cash unless it was set to reinvest). "reinvest" buys more of the paying stock on each pay date, which is what a buy-and-hold comparison against the SPY total-return baseline needs. */
1806
1794
  dividendPolicy?: "cash" | "reinvest";
@@ -460,14 +460,16 @@ export function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
460
460
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
461
461
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
462
462
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
463
+ * @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
463
464
  */
464
- export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0) {
465
+ export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
465
466
  const d = { type: "ChartBar" };
466
467
  setAsset(d, "targetAsset", asset);
467
468
  d["barMinutes"] = barMinutes;
468
469
  d["line"] = line;
469
470
  d["bars"] = bars;
470
471
  d["offsetBars"] = offsetBars;
472
+ d["minutePolicy"] = minutePolicy;
471
473
  return d;
472
474
  }
473
475
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "1.52.0",
3
+ "version": "1.55.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",