@orangecharts/wrun-chart-host 0.9.0 → 0.11.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.
Files changed (252) hide show
  1. package/README.md +2 -0
  2. package/dist/constants/feature-flags.constants.d.ts +15 -1
  3. package/dist/constants/feature-flags.constants.js +130 -24
  4. package/dist/constants/governed-exchanges.constants.d.ts +12 -0
  5. package/dist/constants/governed-exchanges.constants.js +16 -0
  6. package/dist/constants/opra-compliance.constants.d.ts +3 -2
  7. package/dist/constants/opra-compliance.constants.js +3 -2
  8. package/dist/constants/option-venues.constants.d.ts +2 -2
  9. package/dist/constants/scriptEditor/builtin-script-snippets.d.ts +26 -0
  10. package/dist/constants/scriptEditor/builtin-script-snippets.js +6 -0
  11. package/dist/constants/scriptEditor/technicalIndicatorScriptKeys.constants.d.ts +15 -0
  12. package/dist/constants/scriptEditor/technicalIndicatorScriptKeys.constants.js +17 -0
  13. package/dist/constants/venue-presets.constants.d.ts +20 -20
  14. package/dist/constants/venue-presets.constants.js +24 -26
  15. package/dist/host-env.d.ts +21 -5
  16. package/dist/host-env.js +6 -0
  17. package/dist/host-ports.types.d.ts +102 -19
  18. package/dist/index.d.ts +18 -0
  19. package/dist/index.js +18 -0
  20. package/dist/interfaces/cancel-reason.interface.d.ts +1 -1
  21. package/dist/interfaces/cme-realtime.interface.d.ts +16 -9
  22. package/dist/interfaces/cme-realtime.interface.js +6 -3
  23. package/dist/interfaces/kscript-diagnostics.interface.d.ts +12 -0
  24. package/dist/interfaces/opra-realtime.interface.d.ts +1 -5
  25. package/dist/interfaces/prediction-market.interface.d.ts +7 -0
  26. package/dist/interfaces/replay.interface.d.ts +8 -0
  27. package/dist/interfaces/stocks-realtime.interface.d.ts +57 -0
  28. package/dist/interfaces/stocks-realtime.interface.js +32 -0
  29. package/dist/interfaces/wrun-runtime.interface.d.ts +18 -2
  30. package/dist/kscript-data/controls/live-trades-merge.util.d.ts +62 -94
  31. package/dist/kscript-data/controls/live-trades-merge.util.js +106 -171
  32. package/dist/market-data/billing.interface.d.ts +174 -36
  33. package/dist/market-data/billing.interface.js +58 -8
  34. package/dist/market-data/venue.d.ts +152 -7
  35. package/dist/market-data/venues/cme.contract.copy.json +66 -0
  36. package/dist/market-data/venues/cme.d.ts +126 -0
  37. package/dist/market-data/venues/cme.js +133 -0
  38. package/dist/market-data/venues/index.d.ts +294 -7
  39. package/dist/market-data/venues/index.js +49 -6
  40. package/dist/market-data/venues/opra.contract.copy.json +3 -2
  41. package/dist/market-data/venues/opra.d.ts +2 -2
  42. package/dist/market-data/venues/opra.js +5 -2
  43. package/dist/market-data/venues/stocks.contract.copy.json +64 -0
  44. package/dist/market-data/venues/stocks.d.ts +130 -0
  45. package/dist/market-data/venues/stocks.js +117 -0
  46. package/dist/settings-templates/footprint-rows.js +35 -2
  47. package/dist/settings-templates/form-rows.d.ts +2 -1
  48. package/dist/settings-templates/index.js +7 -3
  49. package/dist/settings-templates/indicator-fields.d.ts +5 -4
  50. package/dist/settings-templates/indicator-fields.js +79 -10
  51. package/dist/settings-templates/tool-rules.d.ts +32 -15
  52. package/dist/settings-templates/tool-rules.js +33 -11
  53. package/dist/settings-templates/tool-tables.generated.js +95 -31
  54. package/dist/utility/chart/book-live-bucket.util.d.ts +15 -0
  55. package/dist/utility/chart/book-live-bucket.util.js +47 -0
  56. package/dist/utility/chart/cme-cache-context.util.d.ts +5 -3
  57. package/dist/utility/chart/cme-cache-context.util.js +10 -6
  58. package/dist/utility/chart/cme-realtime.util.js +10 -0
  59. package/dist/utility/chart/cme-user-scripts-gate.util.d.ts +83 -0
  60. package/dist/utility/chart/cme-user-scripts-gate.util.js +142 -0
  61. package/dist/utility/chart/effective-chart-session.util.d.ts +14 -0
  62. package/dist/utility/chart/effective-chart-session.util.js +39 -0
  63. package/dist/utility/chart/host-bar-placement.util.d.ts +28 -0
  64. package/dist/utility/chart/host-bar-placement.util.js +170 -30
  65. package/dist/utility/chart/index-host-tier.util.d.ts +3 -1
  66. package/dist/utility/chart/index-host-tier.util.js +7 -2
  67. package/dist/utility/chart/index-mode-admission.util.js +30 -3
  68. package/dist/utility/chart/kscript-apply-fingerprint.util.js +1 -1
  69. package/dist/utility/chart/kscript-drawing-safe-area.util.d.ts +35 -11
  70. package/dist/utility/chart/kscript-drawing-safe-area.util.js +145 -35
  71. package/dist/utility/chart/kscript-live-coalesce.util.d.ts +9 -7
  72. package/dist/utility/chart/kscript-live-coalesce.util.js +13 -8
  73. package/dist/utility/chart/kscript-live-source-identity.util.d.ts +9 -0
  74. package/dist/utility/chart/kscript-live-source-identity.util.js +10 -1
  75. package/dist/utility/chart/kscript-provenance-keys.util.js +13 -0
  76. package/dist/utility/chart/kscript-standin-identity.leaf.d.ts +5 -1
  77. package/dist/utility/chart/kscript-titancharts-render-keys.constants.d.ts +32 -2
  78. package/dist/utility/chart/kscript-titancharts-render-keys.constants.js +45 -0
  79. package/dist/utility/chart/kscript-venue-policy.util.d.ts +156 -43
  80. package/dist/utility/chart/kscript-venue-policy.util.js +249 -59
  81. package/dist/utility/chart/live-bucket.util.d.ts +24 -8
  82. package/dist/utility/chart/live-bucket.util.js +85 -27
  83. package/dist/utility/chart/market-session-schedule.util.d.ts +10 -0
  84. package/dist/utility/chart/market-session-schedule.util.js +16 -0
  85. package/dist/utility/chart/marketKind.util.js +5 -0
  86. package/dist/utility/chart/mixed-mode.util.d.ts +7 -0
  87. package/dist/utility/chart/mixed-mode.util.js +14 -0
  88. package/dist/utility/chart/opra-read-access.leaf.d.ts +5 -3
  89. package/dist/utility/chart/opra-read-access.leaf.js +5 -3
  90. package/dist/utility/chart/opra-user-scripts-gate.util.d.ts +11 -16
  91. package/dist/utility/chart/opra-user-scripts-gate.util.js +12 -28
  92. package/dist/utility/chart/rth-session.util.d.ts +12 -10
  93. package/dist/utility/chart/rth-session.util.js +25 -21
  94. package/dist/utility/chart/trading-day.util.d.ts +17 -0
  95. package/dist/utility/chart/trading-day.util.js +59 -0
  96. package/dist/utility/chart/window-geometry.leaf.d.ts +8 -0
  97. package/dist/utility/chart/window-geometry.leaf.js +22 -6
  98. package/dist/utility/chart/window-owner.leaf.d.ts +23 -2
  99. package/dist/utility/chart/window-owner.leaf.js +45 -3
  100. package/dist/utility/chart/wrun-bar-session-facts.util.d.ts +33 -15
  101. package/dist/utility/chart/wrun-bar-session-facts.util.js +70 -20
  102. package/dist/utility/chart/wrun-run-result.util.d.ts +12 -0
  103. package/dist/utility/chart/wrun-run-result.util.js +141 -6
  104. package/dist/utility/intl-locale.util.js +5 -0
  105. package/dist/utility/options/option-bar-anchor.util.d.ts +145 -0
  106. package/dist/utility/options/option-bar-anchor.util.js +340 -0
  107. package/dist/utility/options/option-venue.util.d.ts +18 -0
  108. package/dist/utility/options/option-venue.util.js +27 -0
  109. package/dist/utility/scriptEditor/wrun-runtime-diagnostics.leaf.js +4 -0
  110. package/dist/utility/v2/gate-plane.util.d.ts +12 -3
  111. package/dist/utility/v2/gate-plane.util.js +30 -4
  112. package/dist/utility/v2/gate-session-latch.util.js +1 -1
  113. package/dist/utility/v2/stocks-governed.util.d.ts +16 -0
  114. package/dist/utility/v2/stocks-governed.util.js +34 -0
  115. package/dist/utility/wrun/derived-roots.leaf.d.ts +13 -0
  116. package/dist/utility/wrun/derived-roots.leaf.js +27 -0
  117. package/dist/utility/wrun/derived-roots.util.d.ts +205 -0
  118. package/dist/utility/wrun/derived-roots.util.js +451 -0
  119. package/dist/utility/wrun/run-schedule/wrun-chart-gate-reader.util.d.ts +43 -7
  120. package/dist/utility/wrun/run-schedule/wrun-chart-gate-reader.util.js +89 -19
  121. package/dist/utility/wrun/run-schedule/wrun-gate-reader-warm.util.d.ts +9 -4
  122. package/dist/utility/wrun/run-schedule/wrun-gate-reader-warm.util.js +47 -6
  123. package/dist/utility/wrun/run-schedule/wrun-late-reads.util.d.ts +4 -2
  124. package/dist/utility/wrun/run-schedule/wrun-late-reads.util.js +4 -2
  125. package/dist/utility/wrun/run-schedule/wrun-own-candles.util.d.ts +24 -3
  126. package/dist/utility/wrun/run-schedule/wrun-own-candles.util.js +46 -10
  127. package/dist/utility/wrun/sources/lanes/option_daily.js +5 -2
  128. package/dist/utility/wrun/sources/lanes/options_flow.js +5 -2
  129. package/dist/utility/wrun/sources/opra-option-lanes.util.d.ts +64 -19
  130. package/dist/utility/wrun/sources/opra-option-lanes.util.js +105 -35
  131. package/dist/utility/wrun/sources/row-lanes/option_contract_flow.js +2 -1
  132. package/dist/utility/wrun/sources/row-lanes/option_contract_state.js +2 -1
  133. package/dist/utility/wrun/sources/row-lanes/option_prints.d.ts +3 -0
  134. package/dist/utility/wrun/sources/row-lanes/option_prints.js +19 -4
  135. package/dist/utility/wrun/sources/row-lanes/option_strike_flow.js +17 -4
  136. package/dist/utility/wrun/sources/row-lanes/option_strikes.d.ts +52 -13
  137. package/dist/utility/wrun/sources/row-lanes/option_strikes.js +88 -19
  138. package/dist/utility/wrun/sources/row-lanes/option_surface.js +2 -1
  139. package/dist/utility/wrun/sources/wrun-poll-lane.types.d.ts +19 -0
  140. package/dist/utility/wrun/sources/wrun-poll-lanes.util.d.ts +24 -9
  141. package/dist/utility/wrun/sources/wrun-poll-lanes.util.js +41 -10
  142. package/dist/utility/wrun/sources/wrun-row-lane-add-memo.util.d.ts +111 -0
  143. package/dist/utility/wrun/sources/wrun-row-lane-add-memo.util.js +133 -0
  144. package/dist/utility/wrun/sources/wrun-row-lane-first-paint.util.d.ts +15 -3
  145. package/dist/utility/wrun/sources/wrun-row-lane-first-paint.util.js +22 -3
  146. package/dist/utility/wrun/sources/wrun-row-lane.types.d.ts +31 -0
  147. package/dist/utility/wrun/sources/wrun-row-lanes.util.d.ts +197 -13
  148. package/dist/utility/wrun/sources/wrun-row-lanes.util.js +761 -27
  149. package/dist/utility/wrun/wrun-browser-sources.leaf.js +1 -2
  150. package/dist/utility/wrun/wrun-builtin-twin.util.d.ts +12 -0
  151. package/dist/utility/wrun/wrun-builtin-twin.util.js +21 -0
  152. package/dist/utility/wrun/wrun-chart-market-facts.util.d.ts +60 -16
  153. package/dist/utility/wrun/wrun-chart-market-facts.util.js +113 -61
  154. package/dist/utility/wrun/wrun-color-settings.util.d.ts +9 -0
  155. package/dist/utility/wrun/wrun-color-settings.util.js +33 -0
  156. package/dist/utility/wrun/wrun-download-meter.util.d.ts +15 -0
  157. package/dist/utility/wrun/wrun-download-meter.util.js +14 -2
  158. package/dist/utility/wrun/wrun-download-plan.util.d.ts +99 -0
  159. package/dist/utility/wrun/wrun-download-plan.util.js +118 -0
  160. package/dist/utility/wrun/wrun-draft-legend-note.util.d.ts +11 -3
  161. package/dist/utility/wrun/wrun-draft-legend-note.util.js +26 -4
  162. package/dist/utility/wrun/wrun-frames.d.ts +27 -6
  163. package/dist/utility/wrun/wrun-frames.js +73 -10
  164. package/dist/utility/wrun/wrun-handles.util.d.ts +7 -3
  165. package/dist/utility/wrun/wrun-handles.util.js +9 -8
  166. package/dist/utility/wrun/wrun-hosted-wire.util.d.ts +7 -1
  167. package/dist/utility/wrun/wrun-hosted-wire.util.js +12 -2
  168. package/dist/utility/wrun/wrun-hud-looks.util.d.ts +18 -4
  169. package/dist/utility/wrun/wrun-hud-looks.util.js +45 -13
  170. package/dist/utility/wrun/wrun-input-requirements.leaf.d.ts +68 -0
  171. package/dist/utility/wrun/wrun-input-requirements.leaf.js +163 -7
  172. package/dist/utility/wrun/wrun-latest-snapshot.d.ts +11 -0
  173. package/dist/utility/wrun/wrun-leg-close.util.d.ts +59 -23
  174. package/dist/utility/wrun/wrun-leg-close.util.js +186 -28
  175. package/dist/utility/wrun/wrun-live-intake.util.d.ts +35 -15
  176. package/dist/utility/wrun/wrun-live-intake.util.js +243 -126
  177. package/dist/utility/wrun/wrun-live-tick.util.d.ts +13 -5
  178. package/dist/utility/wrun/wrun-live-tick.util.js +279 -99
  179. package/dist/utility/wrun/wrun-market-facts.util.d.ts +13 -3
  180. package/dist/utility/wrun/wrun-market-facts.util.js +13 -3
  181. package/dist/utility/wrun/wrun-market-size-defaults.leaf.d.ts +60 -11
  182. package/dist/utility/wrun/wrun-market-size-defaults.leaf.js +70 -5
  183. package/dist/utility/wrun/wrun-market-size-defaults.util.js +31 -5
  184. package/dist/utility/wrun/wrun-opra-lane.util.d.ts +17 -4
  185. package/dist/utility/wrun/wrun-opra-lane.util.js +6 -4
  186. package/dist/utility/wrun/wrun-option-book-rows.util.d.ts +56 -0
  187. package/dist/utility/wrun/wrun-option-book-rows.util.js +96 -0
  188. package/dist/utility/wrun/wrun-option-strike-flow-forecast.util.d.ts +31 -0
  189. package/dist/utility/wrun/wrun-option-strike-flow-forecast.util.js +119 -0
  190. package/dist/utility/wrun/wrun-option-strike-flow-lane.util.d.ts +23 -6
  191. package/dist/utility/wrun/wrun-option-strike-flow-lane.util.js +47 -11
  192. package/dist/utility/wrun/wrun-option-strike-flow.util.d.ts +86 -19
  193. package/dist/utility/wrun/wrun-option-strike-flow.util.js +168 -62
  194. package/dist/utility/wrun/wrun-option-views.util.d.ts +323 -28
  195. package/dist/utility/wrun/wrun-option-views.util.js +484 -71
  196. package/dist/utility/wrun/wrun-options-chain.util.d.ts +3 -3
  197. package/dist/utility/wrun/wrun-options-chain.util.js +2 -0
  198. package/dist/utility/wrun/wrun-output-style.util.d.ts +6 -2
  199. package/dist/utility/wrun/wrun-output-style.util.js +20 -2
  200. package/dist/utility/wrun/wrun-overlay-drivers.util.d.ts +32 -2
  201. package/dist/utility/wrun/wrun-overlay-drivers.util.js +13 -3
  202. package/dist/utility/wrun/wrun-overlay-lifecycle.util.d.ts +10 -1
  203. package/dist/utility/wrun/wrun-overlay-lifecycle.util.js +52 -4
  204. package/dist/utility/wrun/wrun-overlay-recovery.util.js +3 -1
  205. package/dist/utility/wrun/wrun-overlay-run.util.d.ts +160 -42
  206. package/dist/utility/wrun/wrun-overlay-run.util.js +1244 -209
  207. package/dist/utility/wrun/wrun-pane-format.util.d.ts +2 -1
  208. package/dist/utility/wrun/wrun-pane-format.util.js +7 -3
  209. package/dist/utility/wrun/wrun-panel-mount.util.d.ts +9 -0
  210. package/dist/utility/wrun/wrun-panel-mount.util.js +114 -19
  211. package/dist/utility/wrun/wrun-panel-style.util.d.ts +10 -9
  212. package/dist/utility/wrun/wrun-panel-style.util.js +58 -9
  213. package/dist/utility/wrun/wrun-param-map.util.d.ts +14 -11
  214. package/dist/utility/wrun/wrun-param-map.util.js +10 -5
  215. package/dist/utility/wrun/wrun-param-values.util.d.ts +14 -4
  216. package/dist/utility/wrun/wrun-param-values.util.js +4 -0
  217. package/dist/utility/wrun/wrun-pin-spelling.util.d.ts +15 -2
  218. package/dist/utility/wrun/wrun-pin-spelling.util.js +39 -14
  219. package/dist/utility/wrun/wrun-refusal-surface.util.d.ts +50 -0
  220. package/dist/utility/wrun/wrun-refusal-surface.util.js +68 -0
  221. package/dist/utility/wrun/wrun-refusal.util.d.ts +3 -2
  222. package/dist/utility/wrun/wrun-refusal.util.js +22 -0
  223. package/dist/utility/wrun/wrun-refused-latest.util.d.ts +10 -0
  224. package/dist/utility/wrun/wrun-refused-latest.util.js +12 -0
  225. package/dist/utility/wrun/wrun-registry-errors.util.d.ts +26 -0
  226. package/dist/utility/wrun/wrun-registry-errors.util.js +34 -0
  227. package/dist/utility/wrun/wrun-replay-lane.util.js +3 -2
  228. package/dist/utility/wrun/wrun-row-source.d.ts +11 -0
  229. package/dist/utility/wrun/wrun-run-interval-session.util.d.ts +20 -6
  230. package/dist/utility/wrun/wrun-run-interval-session.util.js +22 -7
  231. package/dist/utility/wrun/wrun-run-interval.util.d.ts +43 -9
  232. package/dist/utility/wrun/wrun-run-interval.util.js +58 -15
  233. package/dist/utility/wrun/wrun-script-inputs.util.d.ts +45 -1
  234. package/dist/utility/wrun/wrun-script-inputs.util.js +112 -4
  235. package/dist/utility/wrun/wrun-setting-words.util.d.ts +7 -3
  236. package/dist/utility/wrun/wrun-setting-words.util.js +13 -5
  237. package/dist/utility/wrun/wrun-socket-row-source.d.ts +27 -2
  238. package/dist/utility/wrun/wrun-socket-row-source.js +118 -8
  239. package/dist/utility/wrun/wrun-source-rows.util.d.ts +29 -18
  240. package/dist/utility/wrun/wrun-source-rows.util.js +61 -27
  241. package/dist/utility/wrun/wrun-style-words.util.js +6 -4
  242. package/dist/utility/wrun/wrun-table-chrome.util.d.ts +3 -2
  243. package/dist/utility/wrun/wrun-table-chrome.util.js +19 -11
  244. package/dist/utility/wrun/wrun-tape-per-order.util.d.ts +2 -0
  245. package/dist/utility/wrun/wrun-tape-per-order.util.js +7 -0
  246. package/dist/utility/wrun/wrun-tape-source.util.d.ts +17 -9
  247. package/dist/utility/wrun/wrun-tape-source.util.js +20 -12
  248. package/dist/utils/replay/replay-buffer-math.d.ts +53 -2
  249. package/dist/utils/replay/replay-buffer-math.js +227 -20
  250. package/dist/workers/constants/socket-slots.d.ts +91 -6
  251. package/dist/workers/constants/socket-slots.js +85 -6
  252. package/package.json +5 -5
@@ -0,0 +1,340 @@
1
+ /**
2
+ * The bars a grouped option read lays (OPTLOAD-READ-CONTRACT 3.2 to 3.4): the app's ONE mirror of tsdb-gateway's anchor
3
+ * rules, read at origin/main d83cbbf20 (pkg/tsdb/selects/option_read_shape.go `barAnchorRules`, `optionReadAnchorReads`,
4
+ * `OptionReadGridOf` and each rule's `fitTier`, `bar`, `session`, `boundary`, `barEnd` and `lays`;
5
+ * option_print_agg_group.go `optionPrintAggCMESessionScopes`; trade_agg.go `cmeRegularSessionAnchor` and
6
+ * `cmeEnergySessionAnchor`; cme.go `cmeSessionDay`, `cmeSessionOpen`, `cmeCurrentSessionLabel` and `isCMEGroupExchange`).
7
+ * Every option read that names a `barAnchor` takes the anchors, their bars, the venues they lay and the reads that take
8
+ * them from here: the strike and contract flow groupings (wrun-option-strike-flow.util), the flow scopes' bars
9
+ * (option-print-agg-scope.worker.util), the prints' per-bar cut (k-option-print.worker), the surface pick
10
+ * (k-option-surface.worker) and the delayed bound's grid (option-read-grid.util). The rules are keyed by pb-common's
11
+ * `BarAnchor`, so an anchor the protocol adds fails the type check until it has a rule here, and the class guard
12
+ * (tests/utility/options/option-bar-anchor.class.spec.ts) fails by name on any other module that names an anchor.
13
+ *
14
+ * - UTC: bars on the Unix epoch, every row counted; its session is the UTC date.
15
+ * - US_EQUITY_RTH, CME_RTH and CME_ENERGY_RTH: a regular session on the New York wall clock (09:30 to 16:00; 09:30 to
16
+ * 16:15, the CME platform session the CME candles keep; 09:00 to 14:30, the energy pit session), weekdays only, bars
17
+ * open + k * width, only rows of [open, close) counted, the last bar of a day short; no holiday is modelled, as the
18
+ * charts model none. The two CME anchors lay bars over the CME group's rows alone, built from tiers dividing 15 and 30
19
+ * minutes; daylight saving comes from the tz database on both sides.
20
+ * - CME_SESSION: the Globex trade date (17:00 Chicago opens the next; a weekday holiday's session belongs to the next
21
+ * trade date on the CME calendar, a weekend day keeps its own date), each bar stamped at the 17:00 open of its first
22
+ * session day; a 604,800 s bar is the ISO week of a trade date. The CME group's alone, taken by OPTION_PRINT_AGG's
23
+ * COIN, MARKET, STRIKE, EXPIRY, EXPIRY_STRIKE and CONTRACT scopes alone, from a tier dividing an hour. It drops no
24
+ * row: an always-on root's weekend rows land on their own dates, as the chart's lattice books them.
25
+ *
26
+ * A decider proves an anchor's bars against the chart's own: a bucket the anchor lays no bar for may fall on a chart bar
27
+ * only where the chart's product holds no trading (`optionChartClosedAt`, its schedule), never because the anchor's own
28
+ * hours leave it out (a CME regular session's weekend on an always-on root).
29
+ *
30
+ * Pure and worker-safe: the zone clock (ny-calendar.util), the CME lattice's trade calendar (cme-session-bucket.util) and
31
+ * the CME products' schedules (market-session-schedule.util).
32
+ */
33
+ import { BarAnchor, BarSpan } from '@orangecharts/orange-v2-pb-common';
34
+ import { cmeSessionBucketMs, isCmeSessionLatticeExchange } from '../chart/cme-session-bucket.util.js';
35
+ import { isGovernedFuturesSymbolOpenAt } from '../chart/market-session-schedule.util.js';
36
+ import { zoneWallMsAt, zoneWallToUtcMs } from '../chart/ny-calendar.util.js';
37
+ const MINUTE_MS = 60_000;
38
+ const HOUR_MS = 3_600_000;
39
+ const DAY_MS = 86_400_000;
40
+ const WEEK_MS = 7 * DAY_MS;
41
+ /** pb-common `BarAnchor` by name: the values a request names (the gateway decodes JSON enums as numbers). */
42
+ export const OPTION_BAR_ANCHOR = Object.freeze({
43
+ UTC: BarAnchor.UTC,
44
+ US_EQUITY_RTH: BarAnchor.US_EQUITY_RTH,
45
+ CME_SESSION: BarAnchor.CME_SESSION,
46
+ CME_RTH: BarAnchor.CME_RTH,
47
+ CME_ENERGY_RTH: BarAnchor.CME_ENERGY_RTH,
48
+ });
49
+ const floorMod = (value, width) => ((value % width) + width) % width;
50
+ /** `fitDayBars`: no bar wider than a day, a day bar from the DAY tier alone, and a whole number of the tier's buckets;
51
+ * a session is the anchor's own to fit. */
52
+ function fitDayBars(tierMs, barMs, session) {
53
+ if (session)
54
+ return true;
55
+ if (barMs > DAY_MS || (barMs === DAY_MS && tierMs !== DAY_MS))
56
+ return false;
57
+ return barMs % tierMs === 0;
58
+ }
59
+ /** `opensBar`: `tMs` opens the bar (or session) it lands in, or lands in none. */
60
+ function opensBar(rule, tMs, barMs, session) {
61
+ const open = session ? rule.sessionOpenMs(tMs) : rule.barOpenMs(tMs, barMs);
62
+ return open === null || open === tMs;
63
+ }
64
+ /** The latest boundary at or before `tMs` on a rule whose bars run unbroken from their open: the open of the bar (or
65
+ * session) holding it, else `tMs` itself (it lands in none). */
66
+ function floorOpensBar(rule, tMs, barMs, session) {
67
+ return (session ? rule.sessionOpenMs(tMs) : rule.barOpenMs(tMs, barMs)) ?? tMs;
68
+ }
69
+ const UTC_RULE = {
70
+ anchor: BarAnchor.UTC,
71
+ name: BarAnchor[BarAnchor.UTC],
72
+ tradeDate: { zone: 'UTC', offsetHours: 0 },
73
+ venues: 'every',
74
+ lays: () => true,
75
+ takes: () => true,
76
+ fitsTier: (tierMs, barMs, session) => tierMs > 0 && fitDayBars(tierMs, barMs, session) && (!session || DAY_MS % tierMs === 0),
77
+ barOpenMs: (tMs, barMs) => {
78
+ if (!Number.isFinite(tMs))
79
+ return null;
80
+ return barMs > 0 ? tMs - floorMod(tMs, barMs) : tMs;
81
+ },
82
+ sessionOpenMs: (tMs) => (Number.isFinite(tMs) ? tMs - floorMod(tMs, DAY_MS) : null),
83
+ isBoundary: (tMs, barMs, session) => opensBar(UTC_RULE, tMs, barMs, session),
84
+ floorBoundaryMs: (tMs, barMs, session) => floorOpensBar(UTC_RULE, tMs, barMs, session),
85
+ barEndMs: (openMs, barMs, session) => openMs + (session ? DAY_MS : barMs),
86
+ };
87
+ /** 1970-01-01, day 0, was a Thursday: a weekend day is a Saturday or a Sunday. */
88
+ const isWeekendDay = (day) => {
89
+ const weekday = floorMod(day + 4, 7);
90
+ return weekday === 0 || weekday === 6;
91
+ };
92
+ /**
93
+ * `regularSessionAnchor`: each weekday's open in the session's zone, bars open + k * width, only rows of [open, close)
94
+ * of that weekday counted, the last bar of a day ending at the close; its session is one trade date of the zone. Built
95
+ * from tiers dividing `tierMs` (the coarsest bucket the open and the close both sit on).
96
+ */
97
+ function regularSessionRule(anchor, session, tierMs, venues) {
98
+ const dayOf = (tMs) => Math.floor(zoneWallMsAt(session.zone, tMs) / DAY_MS);
99
+ const wallAt = (day, minutes) => zoneWallToUtcMs(session.zone, day * DAY_MS + minutes * MINUTE_MS);
100
+ /** `openOf`: the open of the session `tMs` trades in, null on a weekend or outside [open, close) of its day. */
101
+ const openOf = (tMs) => {
102
+ if (!Number.isFinite(tMs))
103
+ return null;
104
+ const day = dayOf(tMs);
105
+ if (!Number.isFinite(day) || isWeekendDay(day))
106
+ return null;
107
+ const open = wallAt(day, session.openMinutes);
108
+ return tMs >= open && tMs < wallAt(day, session.closeMinutes) ? open : null;
109
+ };
110
+ const rule = {
111
+ anchor,
112
+ name: BarAnchor[anchor],
113
+ tradeDate: { zone: session.zone, offsetHours: 0 },
114
+ session: Object.freeze({ ...session }),
115
+ venues,
116
+ lays: (exchange) => venues === 'every' || isCmeSessionLatticeExchange(exchange),
117
+ takes: () => true,
118
+ fitsTier: (tier, barMs, isSession) => tier > 0 && fitDayBars(tier, barMs, isSession) && tierMs % tier === 0,
119
+ barOpenMs: (tMs, barMs) => {
120
+ const open = openOf(tMs);
121
+ if (open === null)
122
+ return null;
123
+ return barMs > 0 ? open + Math.floor((tMs - open) / barMs) * barMs : tMs;
124
+ },
125
+ sessionOpenMs: openOf,
126
+ isBoundary: (tMs, barMs, isSession) => opensBar(rule, tMs, barMs, isSession),
127
+ floorBoundaryMs: (tMs, barMs, isSession) => floorOpensBar(rule, tMs, barMs, isSession),
128
+ barEndMs: (openMs, barMs, isSession) => {
129
+ const closing = wallAt(dayOf(openMs), session.closeMinutes);
130
+ const end = openMs + barMs;
131
+ return !isSession && end < closing ? end : closing;
132
+ },
133
+ };
134
+ return rule;
135
+ }
136
+ /** The CME Group's session clock (cme.go `cmeSessionTimezone`, `cmeSessionOpenHour`). */
137
+ const CME_SESSION_ZONE = 'America/Chicago';
138
+ const CME_SESSION_OPEN_HOUR = 17;
139
+ /** How far apart two session days of one bar lie (`cmeSessionReachDays`): a week bar from a Friday holiday booked
140
+ * into it to its Sunday, a day bar from a holiday to its trade date. */
141
+ const CME_SESSION_REACH_DAYS = 14;
142
+ /** `cmeSessionDay`: the calendar date (days since the epoch) of the session close `tMs` trades toward: the Chicago
143
+ * wall clock's date, moved on at the 17:00 open. */
144
+ const cmeSessionDayOf = (tMs) => Math.floor((zoneWallMsAt(CME_SESSION_ZONE, tMs) + (24 - CME_SESSION_OPEN_HOUR) * HOUR_MS) / DAY_MS);
145
+ /** `cmeSessionOpen`: the 17:00 Chicago open that starts session day `day`, on the calendar day before it. */
146
+ const cmeSessionOpenOf = (day) => zoneWallToUtcMs(CME_SESSION_ZONE, (day - 1) * DAY_MS + CME_SESSION_OPEN_HOUR * HOUR_MS);
147
+ /** `cmeSessionBarLabel`: the candle label (days since the epoch) of the bar holding session day `day`: its trade date
148
+ * (a weekend day its own), or the Monday of that date's week for a week bar. */
149
+ function cmeSessionLabelOf(day, barMs) {
150
+ const label = cmeSessionBucketMs(cmeSessionOpenOf(day), barMs === WEEK_MS ? WEEK_MS : DAY_MS);
151
+ return label === null ? Number.NaN : Math.round(label / DAY_MS);
152
+ }
153
+ /** `cmeSessionBarOpen`: the stamp of the bar holding session day `day`: the open of the first day of the run of
154
+ * session days booked to its label that ends on the label's own day. */
155
+ function cmeSessionBarOpenOf(day, barMs) {
156
+ const label = cmeSessionLabelOf(day, barMs);
157
+ let first = label;
158
+ for (let back = 0; back < CME_SESSION_REACH_DAYS && cmeSessionLabelOf(first - 1, barMs) === label; back += 1) {
159
+ first -= 1;
160
+ }
161
+ return cmeSessionOpenOf(first);
162
+ }
163
+ const CME_SESSION_READS = new Set([
164
+ 'OPTION_PRINT_AGG/COIN',
165
+ 'OPTION_PRINT_AGG/MARKET',
166
+ 'OPTION_PRINT_AGG/STRIKE',
167
+ 'OPTION_PRINT_AGG/EXPIRY',
168
+ 'OPTION_PRINT_AGG/EXPIRY_STRIKE',
169
+ 'OPTION_PRINT_AGG/CONTRACT',
170
+ ]);
171
+ const CME_SESSION_RULE = {
172
+ anchor: BarAnchor.CME_SESSION,
173
+ name: BarAnchor[BarAnchor.CME_SESSION],
174
+ tradeDate: { zone: CME_SESSION_ZONE, offsetHours: 24 - CME_SESSION_OPEN_HOUR },
175
+ venues: 'cme',
176
+ lays: isCmeSessionLatticeExchange,
177
+ takes: (read) => CME_SESSION_READS.has(read),
178
+ // A trade date, a session span or a week, from a tier dividing an hour: the 17:00 open sits on the hour in both of
179
+ // Chicago's offsets.
180
+ fitsTier: (tierMs, barMs, session) => tierMs > 0 && (session || barMs === DAY_MS || barMs === WEEK_MS) && HOUR_MS % tierMs === 0,
181
+ barOpenMs: (tMs, barMs) => {
182
+ if (!Number.isFinite(tMs))
183
+ return null;
184
+ return barMs > 0 ? cmeSessionBarOpenOf(cmeSessionDayOf(tMs), barMs) : tMs;
185
+ },
186
+ sessionOpenMs: (tMs) => (Number.isFinite(tMs) ? cmeSessionBarOpenOf(cmeSessionDayOf(tMs), DAY_MS) : null),
187
+ // A session open no bar straddles: every bar of the session days before it differs from every bar of the days from
188
+ // it on (Christmas's session is Monday 12/28's, so no window starts or ends on the weekend opens between them).
189
+ isBoundary: (tMs, barMs, session) => {
190
+ const width = session ? DAY_MS : barMs;
191
+ if (!(width > 0))
192
+ return true;
193
+ if (!Number.isFinite(tMs))
194
+ return false;
195
+ const day = cmeSessionDayOf(tMs);
196
+ if (cmeSessionOpenOf(day) !== tMs)
197
+ return false;
198
+ const before = new Set();
199
+ for (let back = 1; back <= CME_SESSION_REACH_DAYS; back += 1)
200
+ before.add(cmeSessionLabelOf(day - back, width));
201
+ for (let ahead = 0; ahead < CME_SESSION_REACH_DAYS; ahead += 1) {
202
+ if (before.has(cmeSessionLabelOf(day + ahead, width)))
203
+ return false;
204
+ }
205
+ return true;
206
+ },
207
+ // Boundaries are session opens: the newest one at or before `tMs`, a session day at a time.
208
+ floorBoundaryMs: (tMs, barMs, session) => {
209
+ if (CME_SESSION_RULE.isBoundary(tMs, barMs, session) || !Number.isFinite(tMs))
210
+ return tMs;
211
+ let day = cmeSessionDayOf(tMs);
212
+ for (let back = 0; back <= 2 * CME_SESSION_REACH_DAYS; back += 1, day -= 1) {
213
+ const open = cmeSessionOpenOf(day);
214
+ if (open <= tMs && CME_SESSION_RULE.isBoundary(open, barMs, session))
215
+ return open;
216
+ }
217
+ return tMs;
218
+ },
219
+ // The open of the session day after the bar's last: its label's own day (a day bar), or its week's Sunday.
220
+ barEndMs: (openMs, barMs, session) => {
221
+ const width = session ? DAY_MS : barMs;
222
+ if (!(width > 0))
223
+ return openMs;
224
+ const label = cmeSessionLabelOf(cmeSessionDayOf(openMs), width);
225
+ return cmeSessionOpenOf(label + Math.round(width / DAY_MS));
226
+ },
227
+ };
228
+ const NEW_YORK = 'America/New_York';
229
+ /** Every anchor's rule, by pb-common's value (`barAnchorRules`): a value without a rule fails the type check. */
230
+ export const OPTION_BAR_ANCHOR_RULES = Object.freeze({
231
+ [BarAnchor.UTC]: UTC_RULE,
232
+ [BarAnchor.US_EQUITY_RTH]: regularSessionRule(BarAnchor.US_EQUITY_RTH, { zone: NEW_YORK, openMinutes: 9 * 60 + 30, closeMinutes: 16 * 60 }, 30 * MINUTE_MS, 'every'),
233
+ [BarAnchor.CME_SESSION]: CME_SESSION_RULE,
234
+ [BarAnchor.CME_RTH]: regularSessionRule(BarAnchor.CME_RTH, { zone: NEW_YORK, openMinutes: 9 * 60 + 30, closeMinutes: 16 * 60 + 15 }, 15 * MINUTE_MS, 'cme'),
235
+ [BarAnchor.CME_ENERGY_RTH]: regularSessionRule(BarAnchor.CME_ENERGY_RTH, { zone: NEW_YORK, openMinutes: 9 * 60, closeMinutes: 14 * 60 + 30 }, 30 * MINUTE_MS, 'cme'),
236
+ });
237
+ /** The rules in pb-common's order (UTC, US_EQUITY_RTH, CME_SESSION, CME_RTH, CME_ENERGY_RTH): the order deciders try. */
238
+ const RULES_IN_ORDER = Object.freeze(Object.values(OPTION_BAR_ANCHOR_RULES).sort((a, b) => a.anchor - b.anchor));
239
+ /** The rule of an anchor value, or undefined for a value no rule lays (the gateway refuses it by name). */
240
+ export function optionBarAnchorRuleOf(anchor) {
241
+ return typeof anchor === 'number' && Object.prototype.hasOwnProperty.call(OPTION_BAR_ANCHOR_RULES, anchor)
242
+ ? OPTION_BAR_ANCHOR_RULES[anchor]
243
+ : undefined;
244
+ }
245
+ /**
246
+ * The anchors a read takes on a venue, in pb-common's order: every anchor the read takes that lays every venue's rows,
247
+ * and one laid over a venue group's alone only when the read names a venue of that group (`exchange`, the chain's): the
248
+ * gateway refuses a CME anchor by name on any other venue (OPRA, Deribit) and on a read that names none.
249
+ */
250
+ export function optionBarAnchorsTaken(read, exchange) {
251
+ return RULES_IN_ORDER.filter((rule) => rule.takes(read) && (rule.venues === 'every' || (exchange !== undefined && rule.lays(exchange))));
252
+ }
253
+ /**
254
+ * Where a bar proof may drop a bucket the chart lays a bar for: only at an instant the chart's own product holds no
255
+ * trading at, by its schedule (market-session-schedule.util `isGovernedFuturesSymbolOpenAt`). This is the one drop
256
+ * exemption every decider proves an anchor's bars with (the strike and contract flow groupings, the flow scopes' bars,
257
+ * the prints' per-bar cut). An anchor's own hours are not it: a CME regular session lays no bar on a weekend day, which a
258
+ * weekday product's regular-hours chart lays empty bars for, while an always-on root (crypto since 2026-05-29, 1OZ since
259
+ * 2026-07-24) trades through it. So on an always-on root's chart the session lands on no bars that hold weekend rows,
260
+ * and the decider falls back (UTC bars where they land, else today's fold). A chart off the CME group has no schedule
261
+ * here, so nothing it lays may be dropped.
262
+ */
263
+ export function optionChartClosedAt(grid) {
264
+ if (grid === null || grid === undefined || !isCmeSessionLatticeExchange(grid.exchange))
265
+ return () => false;
266
+ const symbol = grid.symbol;
267
+ return (tMs) => !isGovernedFuturesSymbolOpenAt(symbol, tMs);
268
+ }
269
+ /**
270
+ * The anchor whose sessions are a chain's trade dates (contract 3.4), or undefined where none is: the first anchor the
271
+ * read takes on the venue whose session key (`tradeDate`) is the clock's own rule, a clock that moves its weekends to
272
+ * Monday matching none. New York's clock reads US_EQUITY_RTH's sessions, the UTC date UTC's, the Globex trade date
273
+ * (Chicago's wall clock plus 7 hours) CME_SESSION's on a CME group venue; a CME crypto root's clock (16:00 Chicago,
274
+ * weekends on Monday) is no anchor's.
275
+ */
276
+ export function optionSessionAnchorOf(clock, read, exchange) {
277
+ if (clock.rule.weekendsToMonday === true)
278
+ return undefined;
279
+ return optionBarAnchorsTaken(read, exchange).find((rule) => rule.tradeDate.zone === clock.zone && rule.tradeDate.offsetHours === clock.rule.offsetHours);
280
+ }
281
+ const DAY_SECONDS = DAY_MS / 1000;
282
+ /**
283
+ * The grid an `optionRead` groups on (`OptionReadGridOf`), or null when it groups nothing (no `barSeconds`, span BAR). A
284
+ * day bar is a UTC day's row on UTC and US_EQUITY_RTH, and keeps its anchor on every other (a trade date on
285
+ * CME_SESSION).
286
+ */
287
+ export function optionBarAnchorGridOf(shape) {
288
+ if (typeof shape !== 'object' || shape === null)
289
+ return null;
290
+ const fields = shape;
291
+ const barSeconds = Number(fields.barSeconds ?? 0);
292
+ const seconds = Number.isFinite(barSeconds) && barSeconds > 0 ? barSeconds : 0;
293
+ const session = Number(fields.span ?? BarSpan.BAR) === BarSpan.SESSION;
294
+ if (!session && seconds === 0)
295
+ return null;
296
+ let anchor = Number(fields.barAnchor ?? BarAnchor.UTC);
297
+ if (seconds === DAY_SECONDS && (anchor === BarAnchor.UTC || anchor === BarAnchor.US_EQUITY_RTH)) {
298
+ anchor = BarAnchor.UTC;
299
+ }
300
+ return { anchor, seconds, session };
301
+ }
302
+ /** The open of the bar (or session) holding `tMs` on a grid (`OptionReadGrid.Bar`), null where it lands in none or
303
+ * where no rule lays the grid's anchor. */
304
+ export function optionGridBarOpenMs(grid, tMs) {
305
+ const rule = optionBarAnchorRuleOf(grid.anchor);
306
+ if (rule === undefined)
307
+ return null;
308
+ return grid.session ? rule.sessionOpenMs(tMs) : rule.barOpenMs(tMs, grid.seconds * 1000);
309
+ }
310
+ /** Whether a window may start or end at `tMs` on a grid (`OptionReadGrid.Boundary`); an anchor no rule lays splits
311
+ * nothing. */
312
+ export function optionGridIsBoundary(grid, tMs) {
313
+ const rule = optionBarAnchorRuleOf(grid.anchor);
314
+ return rule === undefined || rule.isBoundary(tMs, grid.seconds * 1000, grid.session);
315
+ }
316
+ /** The latest instant at or before `tMs` a window may end at on a grid, so a window cut there ends with its last whole
317
+ * bar. */
318
+ export function optionGridFloorBoundaryMs(grid, tMs) {
319
+ const rule = optionBarAnchorRuleOf(grid.anchor);
320
+ return rule === undefined ? tMs : rule.floorBoundaryMs(tMs, grid.seconds * 1000, grid.session);
321
+ }
322
+ /** The first instant at or after `tMs` a window may start or end at on a grid (`OptionReadGrid.Ceil`): `tMs` on a
323
+ * boundary, else the end of the bar (or session) holding it, or of the bar after it, until one ends on a boundary. */
324
+ export function optionGridCeilBoundaryMs(grid, tMs) {
325
+ const rule = optionBarAnchorRuleOf(grid.anchor);
326
+ if (rule === undefined)
327
+ return tMs;
328
+ const barMs = grid.seconds * 1000;
329
+ let at = tMs;
330
+ for (let step = 0; step < 4 * CME_SESSION_REACH_DAYS && !rule.isBoundary(at, barMs, grid.session); step += 1) {
331
+ const open = optionGridBarOpenMs(grid, at);
332
+ if (open === null)
333
+ break;
334
+ const end = rule.barEndMs(open, barMs, grid.session);
335
+ if (!(end > at))
336
+ break;
337
+ at = end;
338
+ }
339
+ return at;
340
+ }
@@ -42,6 +42,15 @@ export declare function isOptionVenueVisible(venue: OptionVenue, gates?: OptionV
42
42
  * futures and their options share exchange codes.
43
43
  */
44
44
  export declare function optionVenueForUnderlyingExchange(exchange: Exchange | string): OptionVenue | null;
45
+ /**
46
+ * The provider whose options attach to the market the options seam answers as an underlying (POLYGON `NVDA/USD`
47
+ * resolves to OPRA): `optionVenueForUnderlyingExchange` over that market's exchange. Hand it the seam's market (web:
48
+ * opra-options-gate.util `chartOptionsMarket`), never a chart's own: a stock twin's own code is its crypto venue's, so
49
+ * only the seam knows that its options are its US stock's. Null for no market and for a market no provider lists.
50
+ */
51
+ export declare function optionsMarketUnderlyingVenue(market: {
52
+ exchange?: Exchange | string | null;
53
+ } | null | undefined): OptionVenue | null;
45
54
  /**
46
55
  * The underlying key a venue's chain RPC expects for a parsed contract: the base asset for most
47
56
  * venues, the catalog ticker (base plus quote, `BTCUSDT`) where the venue keys by it.
@@ -50,6 +59,15 @@ export declare function venueUnderlying(venue: OptionVenue, parsed: {
50
59
  root: string;
51
60
  quoteAsset?: string;
52
61
  }): string;
62
+ /**
63
+ * The root coin a venue files a chain's prints and summaries under, read off the key its chain RPCs take: the inverse
64
+ * of `venueUnderlying`, and the one copy of the rule (tests/structure/venue-root-coin-one-rule.spec.ts). A venue that
65
+ * keys by the catalog ticker (`underlyingKey` 'assetTicker') drops the quote asset of the settlement family the key
66
+ * ends in (Binance Options: `BTCUSDT` reads `BTC`). Any other key already is the root (a Deribit coin, a CME futures
67
+ * contract, an OPRA ticker), and so is a key that ends in none of the venue's quote assets. The match ignores case; the
68
+ * root keeps the key's own.
69
+ */
70
+ export declare function venueRootCoin(venue: OptionVenue, underlying: string): string;
53
71
  /**
54
72
  * Where a crypto options indicator reads. `exchange` is the pb-common `Exchange` member name.
55
73
  * Summaries are filed under the root `coin`; trades under `tradeCoin`, which differs on venues
@@ -54,6 +54,18 @@ export function optionVenueForUnderlyingExchange(exchange) {
54
54
  return null;
55
55
  return OPTION_VENUES.find((venue) => venue.underlyingExchanges?.includes(name)) ?? null;
56
56
  }
57
+ /**
58
+ * The provider whose options attach to the market the options seam answers as an underlying (POLYGON `NVDA/USD`
59
+ * resolves to OPRA): `optionVenueForUnderlyingExchange` over that market's exchange. Hand it the seam's market (web:
60
+ * opra-options-gate.util `chartOptionsMarket`), never a chart's own: a stock twin's own code is its crypto venue's, so
61
+ * only the seam knows that its options are its US stock's. Null for no market and for a market no provider lists.
62
+ */
63
+ export function optionsMarketUnderlyingVenue(market) {
64
+ const exchange = market?.exchange;
65
+ return exchange === undefined || exchange === null || exchange === ''
66
+ ? null
67
+ : optionVenueForUnderlyingExchange(exchange);
68
+ }
57
69
  /**
58
70
  * The underlying key a venue's chain RPC expects for a parsed contract: the base asset for most
59
71
  * venues, the catalog ticker (base plus quote, `BTCUSDT`) where the venue keys by it.
@@ -61,6 +73,21 @@ export function optionVenueForUnderlyingExchange(exchange) {
61
73
  export function venueUnderlying(venue, parsed) {
62
74
  return venue.underlyingKey === 'assetTicker' ? `${parsed.root}${parsed.quoteAsset ?? ''}` : parsed.root;
63
75
  }
76
+ /**
77
+ * The root coin a venue files a chain's prints and summaries under, read off the key its chain RPCs take: the inverse
78
+ * of `venueUnderlying`, and the one copy of the rule (tests/structure/venue-root-coin-one-rule.spec.ts). A venue that
79
+ * keys by the catalog ticker (`underlyingKey` 'assetTicker') drops the quote asset of the settlement family the key
80
+ * ends in (Binance Options: `BTCUSDT` reads `BTC`). Any other key already is the root (a Deribit coin, a CME futures
81
+ * contract, an OPRA ticker), and so is a key that ends in none of the venue's quote assets. The match ignores case; the
82
+ * root keeps the key's own.
83
+ */
84
+ export function venueRootCoin(venue, underlying) {
85
+ if (venue.underlyingKey !== 'assetTicker')
86
+ return underlying;
87
+ const key = underlying.toUpperCase();
88
+ const quote = venue.families?.find(({ quoteAsset }) => quoteAsset && key.length > quoteAsset.length && key.endsWith(quoteAsset.toUpperCase()))?.quoteAsset;
89
+ return quote ? underlying.slice(0, -quote.length) : underlying;
90
+ }
64
91
  /**
65
92
  * Where an ordinary chart's coin reads its chain on a plain crypto venue (one the metadata listing
66
93
  * names for the coin): the venue's exchange, the root coin, and the trade key the venue files trades
@@ -270,6 +270,10 @@ export function normalizeRuntimeDiagnostics(value, options = {}) {
270
270
  generation: positiveInteger(raw.generation),
271
271
  type: optionalString(raw.type),
272
272
  details: isObject(raw.details) ? { ...raw.details } : undefined,
273
+ // The row's OPRA mark (computed over OPRA data) survives every normalization: the store's choke point included.
274
+ ...(raw.opra === true ? { opra: true } : {}),
275
+ // The CME mark (computed over CME data) the same way.
276
+ ...(raw.cme === true ? { cme: true } : {}),
273
277
  },
274
278
  ];
275
279
  });
@@ -1,15 +1,22 @@
1
1
  import type { GateProvider } from '../../workers/constants/socket-slots.js';
2
2
  import { isOpraGoverned } from './opra-governed.util.js';
3
+ import { isStocksTapeGoverned } from './stocks-governed.util.js';
3
4
  export interface GatePlane {
4
5
  provider: GateProvider;
5
6
  /** UPPERCASE exchange codes the plane governs. */
6
7
  exchanges: readonly string[];
7
8
  /** The delayed tier's nominal delay, used until the tier frame reports `delay_seconds`. */
8
9
  delayedDefaultSeconds: number;
9
- /** What a logged-out reader request gets: the CME Surface A snapshot, or nothing (OPRA has no snapshot). */
10
- guestReaderTransport: 'surfaceA' | 'none';
10
+ /**
11
+ * What a logged-out visitor gets: the CME Surface A snapshot for reader kinds (`surfaceA`), nothing (`none`: OPRA
12
+ * has no snapshot and its gate takes a session JWT only), or the gate itself (`gate`: the stocks gate admits the
13
+ * guest token on its delayed tiers, reader and feed kinds alike, and registers nothing for it).
14
+ */
15
+ guestReaderTransport: 'surfaceA' | 'none' | 'gate';
11
16
  /** The plane relays order-book types (OPRA is top of book only; its feed publishes none). */
12
17
  servesBooks: boolean;
18
+ /** The gate serves StreamMarketStats; flip per plane once its gate does, with the stats planner routing to it. */
19
+ servesMarketStats: boolean;
13
20
  /** The gate mounts /v3 reader tiers beside /v2 (OPRA: not mounted). */
14
21
  hasV3Tiers: boolean;
15
22
  /**
@@ -21,9 +28,11 @@ export interface GatePlane {
21
28
  mixedWithPublic: 'ungoverned' | 'refuse';
22
29
  }
23
30
  export declare const GATE_PLANES: Readonly<Record<GateProvider, GatePlane>>;
24
- export { isOpraGoverned };
31
+ export { isOpraGoverned, isStocksTapeGoverned };
25
32
  /** The gate plane one exchange code belongs to, or null when no gate governs it. */
26
33
  export declare function gateProviderForExchange(exchange: string | undefined | null): GateProvider | null;
34
+ /** The plane of an exchange whose gate serves no StreamMarketStats (no stats request may name it), else null. */
35
+ export declare function marketStatsUnservedPlane(exchange?: string | null): GateProvider | null;
27
36
  /** One exchange member of a request payload as an UPPERCASE code: a name, or a pb-common enum number. */
28
37
  export declare function exchangeCodeOf(member: unknown): string | null;
29
38
  /**
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * The entitlement-gate planes: which gate serves an exchange, and the per-plane
3
- * facts routing needs (delayed default, guest treatment, books). CME and OPRA
4
- * speak the same gate protocol on different hosts, licences and kick channels.
3
+ * facts routing needs (delayed default, guest treatment, books). CME, OPRA and
4
+ * the US stocks tape speak the same gate protocol on different hosts, licences
5
+ * and kick channels.
5
6
  *
6
7
  * Worker-safe and store-free (imports the interfaces, the slot table and the
7
8
  * CME predicate only), so the worker send path and the main-thread services
@@ -11,8 +12,10 @@
11
12
  import { Exchange } from '@orangecharts/orange-v2-pb-common';
12
13
  import { CME_GOVERNED_EXCHANGES } from '../../interfaces/cme-realtime.interface.js';
13
14
  import { OPRA_DELAY_MINUTES, OPRA_GOVERNED_EXCHANGES } from '../../interfaces/opra-realtime.interface.js';
15
+ import { STOCKS_DELAY_SECONDS, STOCKS_GOVERNED_EXCHANGES } from '../../interfaces/stocks-realtime.interface.js';
14
16
  import { CME_DELAY_MINUTES, isCmeGoverned, normalizeExchangeCode } from '../chart/cme-realtime.util.js';
15
17
  import { isOpraGoverned } from './opra-governed.util.js';
18
+ import { isStocksTapeGoverned } from './stocks-governed.util.js';
16
19
  export const GATE_PLANES = {
17
20
  cme: {
18
21
  provider: 'cme',
@@ -20,6 +23,7 @@ export const GATE_PLANES = {
20
23
  delayedDefaultSeconds: CME_DELAY_MINUTES * 60,
21
24
  guestReaderTransport: 'surfaceA',
22
25
  servesBooks: true,
26
+ servesMarketStats: false,
23
27
  hasV3Tiers: true,
24
28
  mixedWithPublic: 'ungoverned',
25
29
  },
@@ -29,20 +33,42 @@ export const GATE_PLANES = {
29
33
  delayedDefaultSeconds: OPRA_DELAY_MINUTES * 60,
30
34
  guestReaderTransport: 'none',
31
35
  servesBooks: false,
36
+ servesMarketStats: false,
37
+ hasV3Tiers: false,
38
+ mixedWithPublic: 'refuse',
39
+ },
40
+ // The US stocks tape: trades only (no books), no /v3 mount, 15 min + 5 s behind for everyone without the add-on, a
41
+ // guest dials the delayed tiers with the guest token. Tape rows live on the cme cluster only, so a request mixing a
42
+ // tape with an ungoverned venue is refused rather than answered silently empty by the public reader.
43
+ stocks: {
44
+ provider: 'stocks',
45
+ exchanges: STOCKS_GOVERNED_EXCHANGES,
46
+ delayedDefaultSeconds: STOCKS_DELAY_SECONDS,
47
+ guestReaderTransport: 'gate',
48
+ servesBooks: false,
49
+ servesMarketStats: false,
32
50
  hasV3Tiers: false,
33
51
  mixedWithPublic: 'refuse',
34
52
  },
35
53
  };
36
- // The OPRA check is the pure leaf's (opra-governed.util); its importers keep this path.
37
- export { isOpraGoverned };
54
+ // The OPRA and stocks checks are the pure leaves' (opra-governed.util, stocks-governed.util); their importers keep
55
+ // this path.
56
+ export { isOpraGoverned, isStocksTapeGoverned };
38
57
  /** The gate plane one exchange code belongs to, or null when no gate governs it. */
39
58
  export function gateProviderForExchange(exchange) {
40
59
  if (isCmeGoverned(exchange))
41
60
  return 'cme';
42
61
  if (isOpraGoverned(exchange))
43
62
  return 'opra';
63
+ if (isStocksTapeGoverned(exchange))
64
+ return 'stocks';
44
65
  return null;
45
66
  }
67
+ /** The plane of an exchange whose gate serves no StreamMarketStats (no stats request may name it), else null. */
68
+ export function marketStatsUnservedPlane(exchange) {
69
+ const provider = gateProviderForExchange(exchange);
70
+ return provider !== null && !GATE_PLANES[provider].servesMarketStats ? provider : null;
71
+ }
46
72
  /** One exchange member of a request payload as an UPPERCASE code: a name, or a pb-common enum number. */
47
73
  export function exchangeCodeOf(member) {
48
74
  if (typeof member === 'number')
@@ -1,4 +1,4 @@
1
- const heldElsewhere = { cme: false, opra: false };
1
+ const heldElsewhere = { cme: false, opra: false, stocks: false };
2
2
  const listeners = new Set();
3
3
  /** The owner's edge: `true` once a contested kick latched the plane, `false` once this tab took the session back.
4
4
  * Listeners hear a change only, each in turn; one that throws never stops the next. */
@@ -0,0 +1,16 @@
1
+ import type { StocksTapeListingVenue } from '../../interfaces/stocks-realtime.interface.js';
2
+ export declare function isStocksTapeGoverned(exchange: string | undefined | null): boolean;
3
+ /**
4
+ * The name a request carries on the wire for an exchange: a tape code becomes its listing venue (the `Exchange` enum
5
+ * member the stocks gate keys the tape by, `NASDAQ_TAPE` -> `NASDAQ`); any other code is itself. The one translation
6
+ * for requests, applied where an exchange name becomes its enum id (the worker's request args, the series request
7
+ * builder, the markets request builder) and to the channels a stocks live-feed slot sends. Typed to keep the caller's
8
+ * exchange type: the wire names are members of the `Exchange` names a typed channel or request carries.
9
+ */
10
+ export declare function stocksTapeWireExchange<E extends string>(exchange: E): E | StocksTapeListingVenue;
11
+ /**
12
+ * The tape code of a wire name that arrived on a stocks slot (`NASDAQ` -> `NASDAQ_TAPE`); any other name is itself.
13
+ * Applied to frames and registry rows from the stocks gate ALONE: on the public reader and the crypto feed `NASDAQ` is
14
+ * a listing venue of the free lane, never a tape.
15
+ */
16
+ export declare function stocksTapeCodeOfWire(exchange: string): string;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Whether an exchange is governed by the US stocks entitlement gate (one of the three SIP tapes, by the app's tape
3
+ * codes `NYSE_TAPE`, `NYSE_ARCA_TAPE`, `NASDAQ_TAPE`): a pure leaf beside `opra-governed.util`, read by the gate plane
4
+ * table, the live-feed channel classifier, the kScript venue policy and the alert door without the socket-slot table.
5
+ * The plain listing-venue codes (`NYSE`, `NASDAQ`) are NOT governed: they are the free lane's display venues
6
+ * (interfaces/stocks-realtime.interface.ts tells why). The governed codes are the package's byte copy of the stocks
7
+ * interface's list (pinned equal to it by tests/packages/wrun-chart-host/narrowed-constants.spec.ts).
8
+ */
9
+ import { normalizeExchangeCode } from '../chart/cme-realtime.util.js';
10
+ import { STOCKS_GOVERNED_EXCHANGES, STOCKS_TAPE_WIRE_EXCHANGE } from '../../constants/governed-exchanges.constants.js';
11
+ const STOCKS_GOVERNED_EXCHANGE_SET = new Set(STOCKS_GOVERNED_EXCHANGES);
12
+ const TAPE_CODE_OF_WIRE = new Map(Object.entries(STOCKS_TAPE_WIRE_EXCHANGE).map(([code, wire]) => [wire, code]));
13
+ export function isStocksTapeGoverned(exchange) {
14
+ const code = normalizeExchangeCode(exchange);
15
+ return code !== null && STOCKS_GOVERNED_EXCHANGE_SET.has(code);
16
+ }
17
+ /**
18
+ * The name a request carries on the wire for an exchange: a tape code becomes its listing venue (the `Exchange` enum
19
+ * member the stocks gate keys the tape by, `NASDAQ_TAPE` -> `NASDAQ`); any other code is itself. The one translation
20
+ * for requests, applied where an exchange name becomes its enum id (the worker's request args, the series request
21
+ * builder, the markets request builder) and to the channels a stocks live-feed slot sends. Typed to keep the caller's
22
+ * exchange type: the wire names are members of the `Exchange` names a typed channel or request carries.
23
+ */
24
+ export function stocksTapeWireExchange(exchange) {
25
+ return STOCKS_TAPE_WIRE_EXCHANGE[exchange.toUpperCase()] ?? exchange;
26
+ }
27
+ /**
28
+ * The tape code of a wire name that arrived on a stocks slot (`NASDAQ` -> `NASDAQ_TAPE`); any other name is itself.
29
+ * Applied to frames and registry rows from the stocks gate ALONE: on the public reader and the crypto feed `NASDAQ` is
30
+ * a listing venue of the free lane, never a tape.
31
+ */
32
+ export function stocksTapeCodeOfWire(exchange) {
33
+ return TAPE_CODE_OF_WIRE.get(exchange.toUpperCase()) ?? exchange;
34
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The derived-roots table, a leaf with no imports: the wrun `underlying` knob (derived-roots.util) and the built-in
3
+ * options overlays' Chain row (utility/options/options-derived-root.util in the web app) read the same rows.
4
+ */
5
+ /**
6
+ * Contract F's mapping table (the kit's DERIVED_ROOTS in options.ts, row for row): a chart root and the roots whose
7
+ * chains its derived levels read, the first one the default (`defaultDerivedRoot`).
8
+ */
9
+ export declare const WRUN_DERIVED_ROOTS: Readonly<Record<string, readonly string[]>>;
10
+ /** The roots the table maps `chartRoot` to, the default first; none for a root off the table. */
11
+ export declare function wrunDerivedRootsOf(chartRoot: string): readonly string[];
12
+ /** The root `underlying: "derived"` reads on a chart of `chartRoot`: the table's first, undefined off the table. */
13
+ export declare function defaultDerivedRoot(chartRoot: string): string | undefined;
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The derived-roots table, a leaf with no imports: the wrun `underlying` knob (derived-roots.util) and the built-in
3
+ * options overlays' Chain row (utility/options/options-derived-root.util in the web app) read the same rows.
4
+ */
5
+ /**
6
+ * Contract F's mapping table (the kit's DERIVED_ROOTS in options.ts, row for row): a chart root and the roots whose
7
+ * chains its derived levels read, the first one the default (`defaultDerivedRoot`).
8
+ */
9
+ export const WRUN_DERIVED_ROOTS = Object.freeze({
10
+ ES: Object.freeze(['SPX', 'SPY']),
11
+ NQ: Object.freeze(['NDX', 'QQQ']),
12
+ GC: Object.freeze(['GLD']),
13
+ SI: Object.freeze(['SLV']),
14
+ YM: Object.freeze(['DIA']),
15
+ RTY: Object.freeze(['IWM']),
16
+ SPY: Object.freeze(['SPX']),
17
+ QQQ: Object.freeze(['NDX']),
18
+ });
19
+ /** The roots the table maps `chartRoot` to, the default first; none for a root off the table. */
20
+ export function wrunDerivedRootsOf(chartRoot) {
21
+ const key = chartRoot.trim().toUpperCase();
22
+ return Object.prototype.hasOwnProperty.call(WRUN_DERIVED_ROOTS, key) ? WRUN_DERIVED_ROOTS[key] : [];
23
+ }
24
+ /** The root `underlying: "derived"` reads on a chart of `chartRoot`: the table's first, undefined off the table. */
25
+ export function defaultDerivedRoot(chartRoot) {
26
+ return wrunDerivedRootsOf(chartRoot)[0];
27
+ }