alphaspec 0.2.0__tar.gz → 0.2.1__tar.gz

{alphaspec-0.2.0 → alphaspec-0.2.1}/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Changelog
 
+## 0.2.1 — 2026-10-11
+
+Semantics clarified to match what a runtime can apply the same way in backtests and live trading:
+
+- `exits.minHoldDays` counts **trading days** (entry day = 0; weekends and holidays excluded) and holds back
+  `dsl.exit` as well as the other exits. 0.2.0 said calendar days and left `dsl.exit` free.
+- `sizing.scaleIn` add-ons are filled per `execution.fillTiming` (next open under `NEXT_OPEN`), and never on a bar
+  that also closes the position. 0.2.0 said "at the close of the triggering bar".
+- Reference runtime: backtests and live trading now apply both rules identically; live pyramiding honours
+  `maxTotalPct`; live minimum holding is counted from the start of the current position, not the first time the
+  symbol was ever held.
+
 ## 0.2.0 — 2026-10-11
 
 - Contract 0.2 (`schema/0.2/`): trade settings in three optional artifact blocks.
   - `exits`: stop loss, take profit, trailing stop with activation, ATR stop / take profit, minimum holding days
-    (calendar days on every timeframe), no-new-high exit.
+    (see 0.2.1), no-new-high exit.
   - `sizing`: `FIXED_PCT` or `ATR_RISK` per entry, `maxHoldings`, pyramiding `scaleIn`.
   - `execution`: fill timing (`NEXT_OPEN` / `BAR_CLOSE`).
   Semantics in SPEC §4a.

{alphaspec-0.2.0 → alphaspec-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaspec
-Version: 0.2.0
+Version: 0.2.1
 Summary: The auditable contract between alpha and execution: JSON schemas, a validator and lint rules for declarative trading strategies.
 Project-URL: Homepage, https://github.com/openalpha-dev/alphaspec
 Project-URL: Documentation, https://github.com/openalpha-dev/alphaspec#readme

{alphaspec-0.2.0 → alphaspec-0.2.1}/docs/SPEC.md

@@ -99,11 +99,14 @@ Whichever fires first closes the whole position.
 | `atrStopMultiplier` | close ≤ entry − k × ATR(14) |
 | `atrTakeProfitMultiplier` | close ≥ entry + k × ATR(14) |
 | `noNewHighDays` | n trading days pass without a new highest close since entry |
-| `minHoldDays` | (modifies all of the above) none fires within n **calendar** days of entry; `dsl.exit` still does |
+| `minHoldDays` | (modifies everything, `dsl.exit` included) nothing closes the position until n **trading days** after entry |
 
 - Omit a field to leave that exit off. `0` is rejected for the on/off fields: one runtime's
   "disabled" is another's "stop immediately".
-- `minHoldDays` counts calendar days on every timeframe: 3 on a 5m strategy is three days.
+- `minHoldDays` counts trading days in the market's calendar: the entry day is day 0, weekends and
+  holidays do not count, and the meaning is the same on every timeframe (3 on a 5m strategy is three
+  trading days). It holds back rule exits too: its purpose is to keep a fresh position from being
+  shaken out by short-term noise. Leave it out if the strategy should be free to exit at once.
 
 **`sizing`** — how large each position is and how many are held.
 
@@ -112,7 +115,7 @@ Whichever fires first closes the whole position.
 | `positionMode` | `FIXED_PCT` (default): each entry buys `targetPctPerOrder`% of current equity. `ATR_RISK`: each entry is sized so one ATR(14) against it costs `targetPctPerOrder`% of equity; no entry while ATR cannot be computed |
 | `targetPctPerOrder` | the percentage above (required when `sizing` is present) |
 | `maxHoldings` | at most n symbols held at once; buys already queued count as held, so signals on the same bar cannot overshoot; further entries are skipped |
-| `scaleIn` | pyramiding: `{maxAddOns, spacingAtr, maxTotalPct}` — add to a winner each time the close is `spacingAtr` × ATR(14) above the last buy, at most `maxAddOns` times; an add-on that would take the symbol above `maxTotalPct`% of equity is skipped |
+| `scaleIn` | pyramiding: `{maxAddOns, spacingAtr, maxTotalPct}` — add to a winner each time the close is `spacingAtr` × ATR(14) above the last buy, at most `maxAddOns` times; an add-on that would take the symbol above `maxTotalPct`% of equity is skipped; filled per `execution.fillTiming`, never on a bar that closes the position |
 
 Equity is cash plus the market value of all positions. Every buy rounds down to the market's
 lot and is capped by `riskProfile.maxSymbolExposurePct` and by cash. Without a `sizing`

{alphaspec-0.2.0 → alphaspec-0.2.1}/schema/0.2/artifact.schema.json

@@ -756,7 +756,7 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 365,
-          "description": "Calendar days after entry during which none of the exits above fire (dsl.exit still does). Calendar days on every timeframe: 3 on a 5m strategy is three days, not three bars."
+          "description": "Trading days after entry during which nothing closes the position: neither the exits above nor dsl.exit. The entry day is day 0; weekends and market holidays do not count, on every timeframe (3 on a 5m strategy is three trading days). Use it to keep a fresh position from being shaken out by short-term noise; omit it if that is not wanted."
         },
         "noNewHighDays": {
           "type": "integer",
@@ -821,7 +821,7 @@
         "maxAddOns",
         "spacingAtr"
       ],
-      "description": "Pyramiding: add to a winning position each time the close rises spacingAtr × ATR(14) above the last buy price. Each add-on is sized like an entry (positionMode / targetPctPerOrder). Filled at the close of the bar that triggers it.",
+      "description": "Pyramiding: add to a winning position each time the close rises spacingAtr × ATR(14) above the last buy price. Each add-on is sized like an entry (positionMode / targetPctPerOrder). Filled like any other order under execution.fillTiming: at the triggering bar's close (BAR_CLOSE) or at the next bar's open (NEXT_OPEN). No add-on is made on a bar that also closes the position.",
       "properties": {
         "maxAddOns": {
           "type": "integer",

{alphaspec-0.2.0 → alphaspec-0.2.1}/skills/alphaspec/SKILL.md

@@ -72,7 +72,7 @@ Stops, sizing and fill timing go in three optional top-level blocks — not in t
 "execution": { "fillTiming": "NEXT_OPEN" }
 ```
 
-- Other exits: `takeProfitPct`, `atrStopMultiplier`, `atrTakeProfitMultiplier` (ATR 14), `minHoldDays` (calendar days during which stops do not fire). Percentages are 0–100.
+- Other exits: `takeProfitPct`, `atrStopMultiplier`, `atrTakeProfitMultiplier` (ATR 14), `minHoldDays` (trading days after entry during which nothing closes the position, rule exits included). Percentages are 0–100.
 - Leave a field out to turn that exit off; never write `0` (rejected).
 - **Always write `sizing`.** Without it the reference runtime sizes entries by its account limits (up to 60% of equity per symbol), which rarely matches what the user has in mind.
 - Keep `sizing.targetPctPerOrder` ≤ `riskProfile.maxSymbolExposurePct` (AS017).

{alphaspec-0.2.0 → alphaspec-0.2.1}/src/alphaspec/__init__.py

@@ -5,4 +5,4 @@ from .validate import Issue, Report, validate
 
 __all__ = ["CONTRACT_VERSION", "AlphaSpecError", "Client", "EvaluationFailed", "Issue", "Rejected", "Report",
            "load_catalog", "load_schema", "validate"]
-__version__ = "0.2.0"
+__version__ = "0.2.1"