@orangecharts/wrun-chart-host 0.14.0 → 0.16.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 (197) hide show
  1. package/README.md +1 -0
  2. package/dist/constants/economic.constants.d.ts +2 -0
  3. package/dist/constants/economic.constants.js +2 -0
  4. package/dist/constants/feature-flags.constants.d.ts +11 -0
  5. package/dist/constants/feature-flags.constants.js +56 -4
  6. package/dist/constants/feature-limits.constants.d.ts +72 -4
  7. package/dist/constants/feature-limits.constants.js +98 -20
  8. package/dist/constants/interval.constants.js +5 -0
  9. package/dist/constants/kscript-data-interval-restrictions.constants.d.ts +12 -0
  10. package/dist/constants/kscript-data-interval-restrictions.constants.js +14 -0
  11. package/dist/constants/typed-width-fold.leaf.d.ts +50 -0
  12. package/dist/constants/typed-width-fold.leaf.js +99 -0
  13. package/dist/constants/typed-width-source.leaf.d.ts +24 -0
  14. package/dist/constants/typed-width-source.leaf.js +126 -0
  15. package/dist/constants/typed-width.leaf.d.ts +57 -0
  16. package/dist/constants/typed-width.leaf.js +78 -0
  17. package/dist/host-env.d.ts +24 -0
  18. package/dist/host-env.js +22 -0
  19. package/dist/host-ports.types.d.ts +11 -0
  20. package/dist/index.d.ts +4 -0
  21. package/dist/index.js +4 -0
  22. package/dist/interfaces/kscript-diagnostics.interface.d.ts +28 -0
  23. package/dist/interfaces/wrun-runtime.interface.d.ts +107 -4
  24. package/dist/interfaces/wrun-runtime.interface.js +11 -0
  25. package/dist/kscript-data/controls/live-trades-merge.util.d.ts +13 -0
  26. package/dist/kscript-data/controls/live-trades-merge.util.js +16 -1
  27. package/dist/market-data/billing.interface.d.ts +12 -45
  28. package/dist/market-data/billing.interface.js +2 -2
  29. package/dist/market-data/venues/index.d.ts +2 -2
  30. package/dist/market-data/venues/opra.js +3 -3
  31. package/dist/market-data/venues/stocks.contract.copy.json +3 -2
  32. package/dist/market-data/venues/stocks.d.ts +2 -2
  33. package/dist/market-data/venues/stocks.js +10 -9
  34. package/dist/replay/replayLadder.js +7 -4
  35. package/dist/settings-templates/footprint-rows.d.ts +6 -0
  36. package/dist/settings-templates/footprint-rows.js +6 -0
  37. package/dist/settings-templates/frvp-fields.js +14 -0
  38. package/dist/settings-templates/indicator-fields.js +46 -0
  39. package/dist/settings-templates/tool-tables.generated.js +19 -1
  40. package/dist/utility/chart/__fixtures__/live-bucket-regular-golden.json +1706 -0
  41. package/dist/utility/chart/cache-alignment.util.d.ts +65 -0
  42. package/dist/utility/chart/cache-alignment.util.js +124 -24
  43. package/dist/utility/chart/calendar-interval.util.d.ts +83 -1
  44. package/dist/utility/chart/calendar-interval.util.js +152 -4
  45. package/dist/utility/chart/candle-bar-end.util.d.ts +11 -4
  46. package/dist/utility/chart/candle-bar-end.util.js +17 -6
  47. package/dist/utility/chart/chart-time-domain.util.d.ts +3 -0
  48. package/dist/utility/chart/chart-time-domain.util.js +13 -4
  49. package/dist/utility/chart/feed-interval.util.d.ts +4 -2
  50. package/dist/utility/chart/feed-interval.util.js +5 -2
  51. package/dist/utility/chart/fetch-dedupe-policy.util.d.ts +3 -1
  52. package/dist/utility/chart/fetch-dedupe-policy.util.js +19 -1
  53. package/dist/utility/chart/footprint-band.util.d.ts +21 -5
  54. package/dist/utility/chart/footprint-band.util.js +53 -14
  55. package/dist/utility/chart/footprint-display-mode.util.d.ts +2 -0
  56. package/dist/utility/chart/footprint-display-mode.util.js +5 -0
  57. package/dist/utility/chart/governed-lanes-gate.util.d.ts +46 -0
  58. package/dist/utility/chart/governed-lanes-gate.util.js +71 -0
  59. package/dist/utility/chart/governed-lanes-reader-seat.d.ts +14 -0
  60. package/dist/utility/chart/governed-lanes-reader-seat.js +14 -0
  61. package/dist/utility/chart/history-wall.util.d.ts +13 -2
  62. package/dist/utility/chart/history-wall.util.js +11 -4
  63. package/dist/utility/chart/interval-ladder.util.d.ts +5 -2
  64. package/dist/utility/chart/interval-ladder.util.js +44 -4
  65. package/dist/utility/chart/interval-registry.util.d.ts +22 -1
  66. package/dist/utility/chart/interval-registry.util.js +50 -2
  67. package/dist/utility/chart/kscript-data-interval-restriction.leaf.d.ts +32 -4
  68. package/dist/utility/chart/kscript-data-interval-restriction.leaf.js +22 -5
  69. package/dist/utility/chart/kscript-drawing-safe-area.util.d.ts +10 -0
  70. package/dist/utility/chart/kscript-drawing-safe-area.util.js +30 -3
  71. package/dist/utility/chart/kscript-legend-entries.util.d.ts +21 -4
  72. package/dist/utility/chart/kscript-legend-entries.util.js +27 -5
  73. package/dist/utility/chart/kscript-main-grid-stages.util.js +74 -24
  74. package/dist/utility/chart/kscript-row-name.leaf.d.ts +13 -0
  75. package/dist/utility/chart/kscript-row-name.leaf.js +18 -0
  76. package/dist/utility/chart/kscript-venue-policy.util.d.ts +61 -26
  77. package/dist/utility/chart/kscript-venue-policy.util.js +138 -37
  78. package/dist/utility/chart/live-bucket.util.d.ts +29 -4
  79. package/dist/utility/chart/live-bucket.util.js +45 -12
  80. package/dist/utility/chart/market-session.util.d.ts +62 -10
  81. package/dist/utility/chart/market-session.util.js +93 -13
  82. package/dist/utility/chart/marketKind.util.d.ts +1 -7
  83. package/dist/utility/chart/marketKind.util.js +6 -8
  84. package/dist/utility/chart/mixed-mode.util.d.ts +17 -0
  85. package/dist/utility/chart/om-target.util.js +6 -4
  86. package/dist/utility/chart/price-precision.util.d.ts +20 -6
  87. package/dist/utility/chart/price-precision.util.js +34 -7
  88. package/dist/utility/chart/profile-frame-window.util.d.ts +15 -0
  89. package/dist/utility/chart/profile-frame-window.util.js +12 -0
  90. package/dist/utility/chart/rth-session.util.d.ts +3 -1
  91. package/dist/utility/chart/rth-session.util.js +3 -1
  92. package/dist/utility/chart/script-source-session.util.d.ts +43 -0
  93. package/dist/utility/chart/script-source-session.util.js +61 -0
  94. package/dist/utility/chart/typed-width-grid.util.d.ts +23 -0
  95. package/dist/utility/chart/typed-width-grid.util.js +203 -0
  96. package/dist/utility/chart/wrun-run-result.util.d.ts +9 -1
  97. package/dist/utility/chart/wrun-run-result.util.js +8 -2
  98. package/dist/utility/common/transformations.util.d.ts +6 -0
  99. package/dist/utility/common/transformations.util.js +28 -4
  100. package/dist/utility/number-format.util.d.ts +14 -1
  101. package/dist/utility/number-format.util.js +22 -4
  102. package/dist/utility/scriptEditor/wrun-runtime-diagnostics.leaf.d.ts +24 -1
  103. package/dist/utility/scriptEditor/wrun-runtime-diagnostics.leaf.js +113 -0
  104. package/dist/utility/v2/v2-enums.leaf.js +3 -0
  105. package/dist/utility/wrun/wrun-batched-marks.util.d.ts +15 -5
  106. package/dist/utility/wrun/wrun-batched-marks.util.js +70 -20
  107. package/dist/utility/wrun/wrun-canvases.util.d.ts +28 -9
  108. package/dist/utility/wrun/wrun-canvases.util.js +99 -39
  109. package/dist/utility/wrun/wrun-cap-notice.util.d.ts +5 -0
  110. package/dist/utility/wrun/wrun-cap-notice.util.js +23 -0
  111. package/dist/utility/wrun/wrun-card-style.util.d.ts +1 -1
  112. package/dist/utility/wrun/wrun-card-style.util.js +2 -2
  113. package/dist/utility/wrun/wrun-chart-market-facts.util.d.ts +8 -0
  114. package/dist/utility/wrun/wrun-chart-market-facts.util.js +13 -1
  115. package/dist/utility/wrun/wrun-child-overlay-id.util.d.ts +10 -0
  116. package/dist/utility/wrun/wrun-child-overlay-id.util.js +24 -0
  117. package/dist/utility/wrun/wrun-cloud-cme-stamp.util.d.ts +72 -0
  118. package/dist/utility/wrun/wrun-cloud-cme-stamp.util.js +151 -0
  119. package/dist/utility/wrun/wrun-color-facts.util.d.ts +3 -3
  120. package/dist/utility/wrun/wrun-color-facts.util.js +8 -5
  121. package/dist/utility/wrun/wrun-colour-tone.lazy.d.ts +20 -0
  122. package/dist/utility/wrun/wrun-colour-tone.lazy.js +23 -0
  123. package/dist/utility/wrun/wrun-colour-tone.util.d.ts +14 -0
  124. package/dist/utility/wrun/wrun-colour-tone.util.js +119 -0
  125. package/dist/utility/wrun/wrun-dark-pool.util.d.ts +3 -2
  126. package/dist/utility/wrun/wrun-dark-pool.util.js +5 -4
  127. package/dist/utility/wrun/wrun-frames.d.ts +1 -1
  128. package/dist/utility/wrun/wrun-frames.js +2 -2
  129. package/dist/utility/wrun/wrun-handles.util.d.ts +1 -1
  130. package/dist/utility/wrun/wrun-handles.util.js +1 -1
  131. package/dist/utility/wrun/wrun-host.service.d.ts +32 -2
  132. package/dist/utility/wrun/wrun-host.service.js +44 -2
  133. package/dist/utility/wrun/wrun-hosted-wire-caps.d.ts +20 -0
  134. package/dist/utility/wrun/wrun-hosted-wire-caps.js +85 -2
  135. package/dist/utility/wrun/wrun-hosted-wire.util.d.ts +37 -0
  136. package/dist/utility/wrun/wrun-hosted-wire.util.js +54 -0
  137. package/dist/utility/wrun/wrun-hover.util.d.ts +8 -2
  138. package/dist/utility/wrun/wrun-hover.util.js +24 -13
  139. package/dist/utility/wrun/wrun-hud-looks.util.d.ts +1 -0
  140. package/dist/utility/wrun/wrun-hud-looks.util.js +6 -11
  141. package/dist/utility/wrun/wrun-integration-route.util.d.ts +24 -0
  142. package/dist/utility/wrun/wrun-integration-route.util.js +19 -0
  143. package/dist/utility/wrun/wrun-live-intake.util.js +17 -1
  144. package/dist/utility/wrun/wrun-live-patch.util.d.ts +6 -1
  145. package/dist/utility/wrun/wrun-live-patch.util.js +10 -4
  146. package/dist/utility/wrun/wrun-live-tick.util.js +81 -19
  147. package/dist/utility/wrun/wrun-output-words.util.d.ts +14 -0
  148. package/dist/utility/wrun/wrun-output-words.util.js +51 -0
  149. package/dist/utility/wrun/wrun-overlay-drivers.util.d.ts +41 -0
  150. package/dist/utility/wrun/wrun-overlay-drivers.util.js +35 -0
  151. package/dist/utility/wrun/wrun-overlay-result.util.d.ts +6 -1
  152. package/dist/utility/wrun/wrun-overlay-result.util.js +2 -0
  153. package/dist/utility/wrun/wrun-overlay-run.util.d.ts +23 -2
  154. package/dist/utility/wrun/wrun-overlay-run.util.js +305 -51
  155. package/dist/utility/wrun/wrun-panel-mount.util.d.ts +10 -2
  156. package/dist/utility/wrun/wrun-panel-mount.util.js +144 -18
  157. package/dist/utility/wrun/wrun-pin-venues.util.js +5 -1
  158. package/dist/utility/wrun/wrun-refusal.util.d.ts +4 -0
  159. package/dist/utility/wrun/wrun-refusal.util.js +102 -13
  160. package/dist/utility/wrun/wrun-registry-errors.util.d.ts +5 -3
  161. package/dist/utility/wrun/wrun-registry-errors.util.js +5 -3
  162. package/dist/utility/wrun/wrun-row-source-factory.js +17 -1
  163. package/dist/utility/wrun/wrun-row-source.d.ts +8 -1
  164. package/dist/utility/wrun/wrun-run-health.util.d.ts +6 -3
  165. package/dist/utility/wrun/wrun-run-health.util.js +5 -2
  166. package/dist/utility/wrun/wrun-sandbox-row-source.d.ts +1 -1
  167. package/dist/utility/wrun/wrun-sandbox-row-source.js +9 -0
  168. package/dist/utility/wrun/wrun-script-inputs.util.d.ts +25 -8
  169. package/dist/utility/wrun/wrun-script-inputs.util.js +145 -45
  170. package/dist/utility/wrun/wrun-setting-words.util.d.ts +12 -5
  171. package/dist/utility/wrun/wrun-setting-words.util.js +25 -8
  172. package/dist/utility/wrun/wrun-socket-row-source.d.ts +26 -1
  173. package/dist/utility/wrun/wrun-socket-row-source.js +125 -12
  174. package/dist/utility/wrun/wrun-source-rows.util.d.ts +3 -3
  175. package/dist/utility/wrun/wrun-source-rows.util.js +8 -7
  176. package/dist/utility/wrun/wrun-style-names.util.d.ts +23 -0
  177. package/dist/utility/wrun/wrun-style-names.util.js +74 -0
  178. package/dist/utility/wrun/wrun-style-words.util.d.ts +31 -9
  179. package/dist/utility/wrun/wrun-style-words.util.js +46 -15
  180. package/dist/utility/wrun/wrun-trades-lane.util.js +2 -1
  181. package/dist/utility/wrun/wrun-trap-replay.util.d.ts +42 -0
  182. package/dist/utility/wrun/wrun-trap-replay.util.js +63 -0
  183. package/dist/utility/wrun/wrun-volume-profile.util.js +6 -5
  184. package/dist/utility/wrun-display-name.util.d.ts +10 -0
  185. package/dist/utility/wrun-display-name.util.js +21 -0
  186. package/dist/utils/replay/replay-buffer-math.d.ts +2 -0
  187. package/dist/utils/replay/replay-buffer-math.js +2 -0
  188. package/dist/workers/constants/socket-slots.d.ts +1 -1
  189. package/dist/workers/utils/time.worker.util.js +2 -2
  190. package/dist/workers/utils/volume-profile.worker.util.d.ts +9 -0
  191. package/dist/workers/utils/volume-profile.worker.util.js +20 -0
  192. package/dist/workers/wrun/wrun-abi-host.d.ts +3 -0
  193. package/dist/workers/wrun/wrun-abi-host.js +82 -5
  194. package/dist/workers/wrun/wrun-engine-handler.js +53 -4
  195. package/dist/workers/wrun/wrun-trap-frames.leaf.d.ts +28 -0
  196. package/dist/workers/wrun/wrun-trap-frames.leaf.js +108 -0
  197. package/package.json +11 -11
@@ -65,6 +65,10 @@ export declare function askedWindowWithinPlanned(fromSec: number, periodSec: num
65
65
  * - Bucket: Large immutable data, always fetch for buckets in lazy load
66
66
  * - Piece: Small immutable data, only fetch in first load. This is because data cache would have a short TTL if we fetch until now. Piece serves as a small cache before a bucket is formed.
67
67
  * - Remnant: Small mutable data with short TTL, only fetch in first load.
68
+ * - A typed day or week interval (`windowFloorSec` > 0): its chunk grid starts at the window floor (Monday
69
+ * 2000-01-03), so the floating window (from === 0) is judged by its period alone, never as a time on that grid,
70
+ * and an absolute window is cut at the floor first (nothing below it leaves; a window wholly below it plans no ask).
71
+ * Every absolute ask then starts on a piece edge at or after the floor, which is a bar edge of that interval.
68
72
  */
69
73
  export declare function getOptimizedFetchParams(from: number, period: number, interval: string): FetchParams[];
70
74
  /**
@@ -78,6 +82,11 @@ export declare function getOptimizedFetchParams(from: number, period: number, in
78
82
  * floating window (`from: 0`, the same period), so the two ask alike.
79
83
  * - An economic series keeps a signed start (history before 1970) and asks
80
84
  * its short window at a calendar interval.
85
+ * - A typed day or week interval (`windowFloorSec` > 0) starts on the open of
86
+ * the bar holding `nowSec - period`, never before its window floor (Monday
87
+ * 2000-01-03), and still ends at or after now: an absolute, positive start,
88
+ * which the boot lanes never send (they stand down for these intervals). At
89
+ * 20w the 250 bars reach before the floor, so the window starts on it.
81
90
  */
82
91
  export declare function defaultMainWindowSec(input: {
83
92
  nowSec: number;
@@ -88,6 +97,39 @@ export declare function defaultMainWindowSec(input: {
88
97
  fromSec: number;
89
98
  periodSec: number;
90
99
  };
100
+ /**
101
+ * The main demand window cut at the window floor of `interval` (Monday 2000-01-03 on a typed day or week interval):
102
+ * a start before it moves to it and the end stays. Returned as is for every other interval and for a window at or
103
+ * after the floor. refetchDataOfChart applies it to its final range, after every widening (a preserved span, an armed
104
+ * view carried over from an interval with finer bars), so the plan, its asks and the kick base never start below it.
105
+ */
106
+ export declare function cutMainWindowAtFloorSec(window: {
107
+ fromSec: number;
108
+ periodSec: number;
109
+ }, interval: string): {
110
+ fromSec: number;
111
+ periodSec: number;
112
+ };
113
+ /**
114
+ * The last `bars` bars of a typed day or week chart through `nowSec`, the forming bar included (a lite pane's exact
115
+ * window): from the open `bars - 1` bars before the forming bar's, never before the window floor, through now. It
116
+ * holds at most `min(bars, BARS_PER_BUCKET)` bars, so it is one request inside one bucket's worth of bars. Null for
117
+ * every other interval.
118
+ */
119
+ export declare function typedDayWeekLastBarsSec(nowSec: number, bars: number, intervalMs: number): {
120
+ fromSec: number;
121
+ periodSec: number;
122
+ } | null;
123
+ /**
124
+ * A direct historical read (go to date, a detached window) of a typed day or week chart over `[startMs, endMs]`: from
125
+ * the open of the bar holding `startMs` (the gateway drops a bar a window starts inside), never before the window floor,
126
+ * and at most `BARS_PER_BUCKET` bars long (the end is cut, the start kept). Null for every other interval, which keeps
127
+ * its whole-second request.
128
+ */
129
+ export declare function typedDayWeekHistoryAskSec(startMs: number, endMs: number, intervalMs: number): {
130
+ from: number;
131
+ period: number;
132
+ } | null;
91
133
  type MainPlanAskKind = 'bucket' | 'piece' | 'remnant' | 'whole' | 'tail-boot' | 'count';
92
134
  export type MainPlanWhy = 'uncovered-closed-bucket' | 'not-wire-validated' | 'forming-tail' | 'authoritative-reload' | 'tail-boot' | 'dry-identity' | 'unplanned';
93
135
  interface MainPlanCommitWindow {
@@ -247,6 +289,12 @@ export interface MainPlanInput {
247
289
  todayLimit: number;
248
290
  numberOfCandles: number;
249
291
  demandBars: number;
292
+ /**
293
+ * The clock the venue serves through (ms): a delayed tape's cut (the main candles' stream clock), server now
294
+ * elsewhere. The bars a count ask can bring stop there, so the tail ask counts to it (`countLaneBarsSince`).
295
+ * Absent: `nowMs`.
296
+ */
297
+ servedNowMs?: number;
250
298
  };
251
299
  }
252
300
  type MainPlanLane = 'period' | 'count' | 'tail-boot' | 'dry-frontier' | 'whole';
@@ -414,6 +462,23 @@ export interface LandedMainTailVerdict {
414
462
  * Pure.
415
463
  */
416
464
  export declare function mergeLandedMainTailVerdict(held: LandedMainTailVerdict | null | undefined, landed: LandedMainTailVerdict): LandedMainTailVerdict;
465
+ /**
466
+ * The bars a count-fetched series (tradfi, forex, commodity, dex: "the newest N bars at or before an anchor") can
467
+ * have opened since its tail, the ONE count every count-lane tail ask is sized by (the main plan's count lane and the
468
+ * wake resync's): from the later of the tail bar and the instant the wire already answered through past it
469
+ * (`provenThroughMs`, the entry's tail verdict: a count reply anchored at now answers for every bar from its first row
470
+ * to its anchor, count-ask-receipt.util, so on a venue that printed nothing since its newest row the reply proves the
471
+ * closure), to the clock the venue serves through (`servedNowMs`: a delayed tape's cut, never server now, which
472
+ * counted the 15-minute delay as missing bars). Clock time between those two, never a calendar: the wire's word is
473
+ * what shrinks the count, so nothing here can hide a bar (an unmodelled holiday, an extended or overnight session).
474
+ * Pure.
475
+ */
476
+ export declare function countLaneBarsSince(input: {
477
+ tailMs: number;
478
+ provenThroughMs?: number | null;
479
+ servedNowMs: number;
480
+ intervalMs: number;
481
+ }): number;
417
482
  export declare function planMainRefetchAsks(input: MainPlanInput): MainPlanResult;
418
483
  /**
419
484
  * The span a staged family mounts (fix-forward lane S1, the 2026-09-27 ETH
@@ -1,6 +1,6 @@
1
1
  import { Intervals } from '../../constants/interval.constants.js';
2
2
  import { serverNowMs } from '../auth/server-clock.util.js';
3
- import { barEndMs, barStartMs, isCalendarIntervalMs } from './calendar-interval.util.js';
3
+ import { barEndMs, barStartMs, chunkCeilMs, chunkCeilSec, chunkFloorMs, chunkFloorSec, isCalendarIntervalMs, isOnChunkGridSec, windowFloorSec, } from './calendar-interval.util.js';
4
4
  export const BARS_PER_BUCKET = 250;
5
5
  export const BARS_PER_PIECE = 50;
6
6
  const MIN_PERIOD_SECONDS = 60;
@@ -16,8 +16,8 @@ function getSafeNowUpperBound() {
16
16
  export function alignTimestampToBucket(timestampMs, intervalMs, direction = 'floor') {
17
17
  const bucketSize = BARS_PER_BUCKET * intervalMs;
18
18
  const result = direction === 'floor'
19
- ? Math.floor(timestampMs / bucketSize) * bucketSize
20
- : Math.ceil(timestampMs / bucketSize) * bucketSize;
19
+ ? chunkFloorMs(timestampMs, bucketSize, intervalMs)
20
+ : chunkCeilMs(timestampMs, bucketSize, intervalMs);
21
21
  return Math.round(result);
22
22
  }
23
23
  /**
@@ -38,7 +38,7 @@ export function completeBucketStartsForWindow(fromSec, periodSec, intervalMs, no
38
38
  return [];
39
39
  const windowEndSec = fromSec + periodSec;
40
40
  const nowSec = Math.floor(nowMs / 1000);
41
- const firstStart = Math.ceil(fromSec / bucketSec) * bucketSec;
41
+ const firstStart = chunkCeilSec(fromSec, bucketSec, intervalMs);
42
42
  const out = [];
43
43
  for (let start = firstStart; start + bucketSec <= windowEndSec; start += bucketSec) {
44
44
  if (start + bucketSec > nowSec)
@@ -113,12 +113,26 @@ export function askedWindowWithinPlanned(fromSec, periodSec, payload) {
113
113
  * - Bucket: Large immutable data, always fetch for buckets in lazy load
114
114
  * - Piece: Small immutable data, only fetch in first load. This is because data cache would have a short TTL if we fetch until now. Piece serves as a small cache before a bucket is formed.
115
115
  * - Remnant: Small mutable data with short TTL, only fetch in first load.
116
+ * - A typed day or week interval (`windowFloorSec` > 0): its chunk grid starts at the window floor (Monday
117
+ * 2000-01-03), so the floating window (from === 0) is judged by its period alone, never as a time on that grid,
118
+ * and an absolute window is cut at the floor first (nothing below it leaves; a window wholly below it plans no ask).
119
+ * Every absolute ask then starts on a piece edge at or after the floor, which is a bar edge of that interval.
116
120
  */
117
121
  export function getOptimizedFetchParams(from, period, interval) {
118
122
  const intervalMs = Intervals.map_unit[interval];
119
123
  const bucketSize = (BARS_PER_BUCKET * intervalMs) / 1000;
120
124
  const pieceSize = (BARS_PER_PIECE * intervalMs) / 1000;
121
- const isBucket = from % bucketSize === 0 && period === bucketSize;
125
+ const floorSec = windowFloorSec(intervalMs);
126
+ if (floorSec > 0 && from !== 0 && from < floorSec) {
127
+ const endSec = from + period;
128
+ if (!(endSec > floorSec))
129
+ return [];
130
+ from = floorSec;
131
+ period = endSec - floorSec;
132
+ }
133
+ // The floating window has no time on the grid: at origin 0 every grid test of 0 holds, so it is on the grid.
134
+ const onGrid = (chunkSize) => (floorSec > 0 && from === 0) || isOnChunkGridSec(from, chunkSize, intervalMs);
135
+ const isBucket = onGrid(bucketSize) && period === bucketSize;
122
136
  // An already-canonical window leaves as ONE request. The floating latest
123
137
  // window (from === 0) always does: the boot lanes (hoist, early dispatch)
124
138
  // key their stand-down on that single-request plan. An ABSOLUTE
@@ -127,8 +141,8 @@ export function getOptimizedFetchParams(from, period, interval) {
127
141
  // through and fans out into buckets below, so every chunk is a stable key
128
142
  // on the backend grid and on the bucket caches, which refuse anything over
129
143
  // BARS_PER_BUCKET and would otherwise never persist the range.
130
- const isPiece = from % pieceSize === 0 && period % pieceSize === 0 && (from === 0 || period <= bucketSize);
131
- const isRemnant = from % pieceSize === 0 && period % pieceSize !== 0 && period < pieceSize;
144
+ const isPiece = onGrid(pieceSize) && period % pieceSize === 0 && (from === 0 || period <= bucketSize);
145
+ const isRemnant = onGrid(pieceSize) && period % pieceSize !== 0 && period < pieceSize;
132
146
  if (isBucket || isPiece || isRemnant) {
133
147
  return [
134
148
  {
@@ -139,8 +153,8 @@ export function getOptimizedFetchParams(from, period, interval) {
139
153
  }
140
154
  const safeNow = getSafeNowUpperBound();
141
155
  // Calculate time range in milliseconds
142
- // Interpret from=0 as "latest window ending at safeNow"
143
- const fromMs = from === 0 ? Math.max(0, safeNow - period * 1000) : from * 1000;
156
+ // Interpret from=0 as "latest window ending at safeNow", never before the window floor
157
+ const fromMs = from === 0 ? Math.max(floorSec * 1000, safeNow - period * 1000) : from * 1000;
144
158
  // Never let the end exceed the safeNow truncation
145
159
  const toMs = Math.min(fromMs + period * 1000, safeNow);
146
160
  // Align to bucket boundaries for cache efficiency
@@ -193,14 +207,68 @@ const ECONOMIC_CALENDAR_WINDOW_SEC = new Map([
193
207
  * floating window (`from: 0`, the same period), so the two ask alike.
194
208
  * - An economic series keeps a signed start (history before 1970) and asks
195
209
  * its short window at a calendar interval.
210
+ * - A typed day or week interval (`windowFloorSec` > 0) starts on the open of
211
+ * the bar holding `nowSec - period`, never before its window floor (Monday
212
+ * 2000-01-03), and still ends at or after now: an absolute, positive start,
213
+ * which the boot lanes never send (they stand down for these intervals). At
214
+ * 20w the 250 bars reach before the floor, so the window starts on it.
196
215
  */
197
216
  export function defaultMainWindowSec(input) {
198
217
  const periodSec = (input.economic ? ECONOMIC_CALENDAR_WINDOW_SEC.get(input.interval) : undefined) ?? input.barsPeriodSec;
199
218
  const fromSec = Math.floor(input.nowSec - periodSec);
219
+ const intervalMs = Intervals.map_unit[input.interval];
220
+ const floorSec = input.economic ? 0 : windowFloorSec(intervalMs);
221
+ if (floorSec > 0) {
222
+ const startSec = Math.max(floorSec, barStartMs(fromSec * 1000, intervalMs) / 1000);
223
+ // Floored to a bar open, the window keeps its end (now): the forming bar stays inside it.
224
+ return { fromSec: startSec, periodSec: Math.max(periodSec, fromSec + periodSec - startSec) };
225
+ }
200
226
  return { fromSec: input.economic ? fromSec : Math.max(0, fromSec), periodSec };
201
227
  }
202
- function pieceFloorSec(sec, pieceSec) {
203
- return Math.floor(sec / pieceSec) * pieceSec;
228
+ /**
229
+ * The main demand window cut at the window floor of `interval` (Monday 2000-01-03 on a typed day or week interval):
230
+ * a start before it moves to it and the end stays. Returned as is for every other interval and for a window at or
231
+ * after the floor. refetchDataOfChart applies it to its final range, after every widening (a preserved span, an armed
232
+ * view carried over from an interval with finer bars), so the plan, its asks and the kick base never start below it.
233
+ */
234
+ export function cutMainWindowAtFloorSec(window, interval) {
235
+ const floorSec = windowFloorSec(Intervals.map_unit[interval]);
236
+ if (!(floorSec > 0) || window.fromSec >= floorSec)
237
+ return window;
238
+ return { fromSec: floorSec, periodSec: Math.max(0, window.fromSec + window.periodSec - floorSec) };
239
+ }
240
+ /**
241
+ * The last `bars` bars of a typed day or week chart through `nowSec`, the forming bar included (a lite pane's exact
242
+ * window): from the open `bars - 1` bars before the forming bar's, never before the window floor, through now. It
243
+ * holds at most `min(bars, BARS_PER_BUCKET)` bars, so it is one request inside one bucket's worth of bars. Null for
244
+ * every other interval.
245
+ */
246
+ export function typedDayWeekLastBarsSec(nowSec, bars, intervalMs) {
247
+ const floorSec = windowFloorSec(intervalMs);
248
+ if (!(floorSec > 0))
249
+ return null;
250
+ const count = Math.max(1, Math.min(BARS_PER_BUCKET, Math.floor(bars)));
251
+ const formingSec = barStartMs(nowSec * 1000, intervalMs) / 1000;
252
+ const fromSec = Math.max(floorSec, formingSec - (count - 1) * (intervalMs / 1000));
253
+ return { fromSec, periodSec: Math.max(1, Math.ceil(nowSec) - fromSec) };
254
+ }
255
+ /**
256
+ * A direct historical read (go to date, a detached window) of a typed day or week chart over `[startMs, endMs]`: from
257
+ * the open of the bar holding `startMs` (the gateway drops a bar a window starts inside), never before the window floor,
258
+ * and at most `BARS_PER_BUCKET` bars long (the end is cut, the start kept). Null for every other interval, which keeps
259
+ * its whole-second request.
260
+ */
261
+ export function typedDayWeekHistoryAskSec(startMs, endMs, intervalMs) {
262
+ const floorSec = windowFloorSec(intervalMs);
263
+ if (!(floorSec > 0))
264
+ return null;
265
+ const intervalSec = intervalMs / 1000;
266
+ const from = Math.max(floorSec, barStartMs(startMs, intervalMs) / 1000);
267
+ const end = Math.min(Math.ceil(endMs / 1000), from + BARS_PER_BUCKET * intervalSec);
268
+ return { from, period: Math.max(intervalSec, end - from) };
269
+ }
270
+ function pieceFloorSec(sec, pieceSec, intervalMs) {
271
+ return chunkFloorSec(sec, pieceSec, intervalMs);
204
272
  }
205
273
  function wholeAsk(window, why) {
206
274
  return { kind: 'whole', from: window.fromSec, period: window.periodSec, why };
@@ -318,11 +386,11 @@ function unprovenMountHealAsks(input, receipts, reachFromSec, intervalSec) {
318
386
  continue;
319
387
  if (receipts.some(([fromTs, toTs]) => fromTs <= ts && ts <= toTs))
320
388
  continue;
321
- buckets.add(Math.floor(Math.floor(ts / 1000) / bucketSec) * bucketSec);
389
+ buckets.add(chunkFloorSec(Math.floor(ts / 1000), bucketSec, intervalSec * 1000));
322
390
  }
323
391
  const firstTs = paint.firstTs;
324
392
  const pending = input.identityPending ?? [];
325
- const reachPieceEndSec = Math.ceil(reachFromSec / pieceSec) * pieceSec;
393
+ const reachPieceEndSec = chunkCeilSec(reachFromSec, pieceSec, intervalSec * 1000);
326
394
  const asks = [];
327
395
  for (const b of [...buckets].sort((x, y) => y - x)) {
328
396
  const end = Math.min(b + bucketSec, reachPieceEndSec);
@@ -332,7 +400,7 @@ function unprovenMountHealAsks(input, receipts, reachFromSec, intervalSec) {
332
400
  // the rows it holds are proven, the ask starts at its last piece.
333
401
  const cover = typeof firstTs === 'number' ? receiptHoldingBucketStart(receipts, b * 1000) : undefined;
334
402
  if (cover !== undefined) {
335
- const start = Math.max(b, pieceFloorSec(Math.floor(cover[1] / 1000), pieceSec));
403
+ const start = Math.max(b, pieceFloorSec(Math.floor(cover[1] / 1000), pieceSec, intervalSec * 1000));
336
404
  asks.push(...tailAsks(start, end, pieceSec, intervalSec, 'not-wire-validated').map((ask) => withCommitWindow({ ...ask, coverEndMs: cover[1] })));
337
405
  continue;
338
406
  }
@@ -350,7 +418,9 @@ function unprovenMountBucketsOf(heal, intervalSec) {
350
418
  if (heal.length === 0)
351
419
  return {};
352
420
  const bucketSec = BARS_PER_BUCKET * intervalSec;
353
- return { unprovenMountBuckets: [...new Set(heal.map((ask) => Math.floor(ask.from / bucketSec) * bucketSec))] };
421
+ return {
422
+ unprovenMountBuckets: [...new Set(heal.map((ask) => chunkFloorSec(ask.from, bucketSec, intervalSec * 1000)))],
423
+ };
354
424
  }
355
425
  /**
356
426
  * The dry lane's KNOWN FRONTIER (fix-forward S2, the 2026-09-27 CME weekend
@@ -553,6 +623,26 @@ export function mergeLandedMainTailVerdict(held, landed) {
553
623
  : Math.max(held.closedAtMs, landed.closedAtMs);
554
624
  return { tailTs: landed.tailTs, throughMs: Math.max(held.throughMs, landed.throughMs), closedAtMs };
555
625
  }
626
+ /**
627
+ * The bars a count-fetched series (tradfi, forex, commodity, dex: "the newest N bars at or before an anchor") can
628
+ * have opened since its tail, the ONE count every count-lane tail ask is sized by (the main plan's count lane and the
629
+ * wake resync's): from the later of the tail bar and the instant the wire already answered through past it
630
+ * (`provenThroughMs`, the entry's tail verdict: a count reply anchored at now answers for every bar from its first row
631
+ * to its anchor, count-ask-receipt.util, so on a venue that printed nothing since its newest row the reply proves the
632
+ * closure), to the clock the venue serves through (`servedNowMs`: a delayed tape's cut, never server now, which
633
+ * counted the 15-minute delay as missing bars). Clock time between those two, never a calendar: the wire's word is
634
+ * what shrinks the count, so nothing here can hide a bar (an unmodelled holiday, an extended or overnight session).
635
+ * Pure.
636
+ */
637
+ export function countLaneBarsSince(input) {
638
+ const { tailMs, provenThroughMs, servedNowMs, intervalMs } = input;
639
+ if (!(intervalMs > 0) || !Number.isFinite(tailMs) || !Number.isFinite(servedNowMs))
640
+ return 0;
641
+ const fromMs = typeof provenThroughMs === 'number' && Number.isFinite(provenThroughMs) && provenThroughMs > tailMs
642
+ ? provenThroughMs
643
+ : tailMs;
644
+ return Math.max(0, Math.floor((servedNowMs - fromMs) / intervalMs));
645
+ }
556
646
  export function planMainRefetchAsks(input) {
557
647
  const { window } = input;
558
648
  const none = {
@@ -575,8 +665,21 @@ export function planMainRefetchAsks(input) {
575
665
  if (input.indexMode) {
576
666
  const lane = input.countLane;
577
667
  const cachedLastTs = paint ? (lane?.cachedLastTs ?? paint.lastTs) : undefined;
668
+ const todayLimit = lane?.todayLimit ?? 0;
669
+ const cap = Math.max(lane?.numberOfCandles ?? 0, lane?.demandBars ?? 0);
670
+ const windowLimit = cap > 0 ? Math.min(Math.max(todayLimit, 1), cap) : Math.max(todayLimit, 1);
578
671
  if (paint && typeof cachedLastTs === 'number' && Number.isFinite(cachedLastTs)) {
579
- const barsSince = Math.max(0, Math.floor((input.nowMs - cachedLastTs) / intervalMs));
672
+ // The cached last bar and every bar the venue can have opened since (countLaneBarsSince): never a clock span
673
+ // the wire already answered for, so a closed or quiet market asks two bars once a reply has answered past its
674
+ // tail, where it asked the whole closure (1,973 bars on a Sunday, the 2026-11-08 INT AAPL dump). The ask still
675
+ // bridges every bar nothing proves (a merge over the painted rows needs no hole): a rebuild that would ask more
676
+ // than the window keeps its window send instead (boot-fetch-hoist `count-entry-rebuild`, titan-charts' count boot).
677
+ const limit = countLaneBarsSince({
678
+ tailMs: cachedLastTs,
679
+ provenThroughMs: paint.tailValidatedThroughMs,
680
+ servedNowMs: lane?.servedNowMs ?? input.nowMs,
681
+ intervalMs,
682
+ }) + 2;
580
683
  const fromSec = Math.floor(cachedLastTs / 1000);
581
684
  return {
582
685
  lane: 'count',
@@ -585,7 +688,7 @@ export function planMainRefetchAsks(input) {
585
688
  kind: 'count',
586
689
  from: nowSec,
587
690
  period: 0,
588
- limit: barsSince + 2,
691
+ limit,
589
692
  why: 'forming-tail',
590
693
  commitWindow: { fromSec, toSec: nowSec },
591
694
  },
@@ -594,12 +697,9 @@ export function planMainRefetchAsks(input) {
594
697
  reason: 'count-hit',
595
698
  };
596
699
  }
597
- const todayLimit = lane?.todayLimit ?? 0;
598
- const cap = Math.max(lane?.numberOfCandles ?? 0, lane?.demandBars ?? 0);
599
- const limit = cap > 0 ? Math.min(Math.max(todayLimit, 1), cap) : Math.max(todayLimit, 1);
600
700
  return {
601
701
  lane: 'count',
602
- asks: [{ kind: 'count', from: nowSec, period: 0, limit, why: 'uncovered-closed-bucket' }],
702
+ asks: [{ kind: 'count', from: nowSec, period: 0, limit: windowLimit, why: 'uncovered-closed-bucket' }],
603
703
  ...none,
604
704
  reason: 'count-miss',
605
705
  };
@@ -695,7 +795,7 @@ export function planMainRefetchAsks(input) {
695
795
  const pendingBuckets = [];
696
796
  const covers = [];
697
797
  let partialBuckets = 0;
698
- for (let b = Math.floor(window.fromSec / bucketSec) * bucketSec; b < windowEndSec; b += bucketSec) {
798
+ for (let b = chunkFloorSec(window.fromSec, bucketSec, intervalMs); b < windowEndSec; b += bucketSec) {
699
799
  const bEnd = b + bucketSec;
700
800
  const lastBarMs = (bEnd - intervalSec) * 1000;
701
801
  const bucketHeldFromFirstRow = firstTs !== undefined && b * 1000 >= firstTs;
@@ -728,7 +828,7 @@ export function planMainRefetchAsks(input) {
728
828
  // before this bucket when the receipt is an island).
729
829
  partialBuckets += 1;
730
830
  covers.push({ bucket: b, coverEndMs: cover[1], skipped: false });
731
- const start = Math.max(b, pieceFloorSec(Math.floor(cover[1] / 1000), pieceSec));
831
+ const start = Math.max(b, pieceFloorSec(Math.floor(cover[1] / 1000), pieceSec, intervalMs));
732
832
  asks.push(...tailAsks(start, end, pieceSec, intervalSec, end >= nowSec ? 'forming-tail' : 'not-wire-validated').map((ask) => ({ ...ask, coverEndMs: cover[1] })));
733
833
  continue;
734
834
  }
@@ -791,7 +891,7 @@ export function planMainRefetchAsks(input) {
791
891
  asks.sort((a, b) => b.from - a.from);
792
892
  // Rows older than the bucket holding the window start that no receipt
793
893
  // covers heal after the demand asks, bounded by the rows.
794
- const heal = unprovenMountHealAsks(input, receipts, Math.floor(window.fromSec / bucketSec) * bucketSec, intervalSec);
894
+ const heal = unprovenMountHealAsks(input, receipts, chunkFloorSec(window.fromSec, bucketSec, intervalMs), intervalSec);
795
895
  return {
796
896
  lane: 'period',
797
897
  asks: [...asks.map(withCommitWindow), ...heal],
@@ -1,3 +1,33 @@
1
+ /**
2
+ * Calendar bars (1M 3M 6M 1Y): where one starts and where it ends.
3
+ *
4
+ * The gateway buckets them on UTC calendar boundaries (kiyotaka-go
5
+ * GetIntervalStart, tsdb-gateway !2190): a month on the 1st at 00:00, quarters
6
+ * in January, April, July and October, halves in January and July, years on
7
+ * January 1. Their length varies (28 to 31 days a month), so the fixed floor
8
+ * `ts - ts % ms` on the chart's average-month length lands mid-month and splits
9
+ * the forming bar. Every writer that floors a timestamp onto a bar, or asks
10
+ * when a bar closes, goes through `barStartMs` / `barEndMs`; one that steps a
11
+ * bar back goes through `prevBarStartMs`, and one that sizes a whole bar's worth
12
+ * of finer bars through `calendarLongestBarMs`.
13
+ *
14
+ * Keyed on the exact lengths Intervals.map_unit gives the calendar labels; any
15
+ * other length is fixed-length. The 35 typed day and week lengths (2d to 20d,
16
+ * 2w to 20w) ride a fixed grid that starts on Monday 2000-01-03, the gateway's
17
+ * grid for them; every other fixed length rides the epoch grid. A leaf:
18
+ * workers and live writers read it.
19
+ */
20
+ import { isTypedDayWeekMs } from './candle-bar-end.util.js';
21
+ export { isTypedDayWeekMs };
22
+ /** Where the bar grid of a typed day or week length starts: Monday 2000-01-03 00:00 UTC (unix day 10959). */
23
+ export declare const TYPED_DAY_WEEK_GRID_ORIGIN_MS = 946857600000;
24
+ /**
25
+ * The engine's bar grid origin (`barGridOriginMs`) for a chart on `intervalMs`: Monday 2000-01-03 on a typed day or
26
+ * week interval, whose bars count from it, and absent on every other chart (the engine's epoch grid). Written on the
27
+ * live settings so it follows an interval switch both ways (refetchDataOfChart calls it on every dataset load); an
28
+ * engine that does not know the setting ignores it.
29
+ */
30
+ export declare function stampBarGridOrigin(settings: object | null | undefined, intervalMs: number): void;
1
31
  /** Months per bar of each calendar label. */
2
32
  export declare const CALENDAR_INTERVAL_MONTHS: Readonly<Record<string, number>>;
3
33
  /** Months per bar for a calendar length, null for a fixed-length interval. */
@@ -6,7 +36,34 @@ export declare function isCalendarIntervalMs(intervalMs: number): boolean;
6
36
  export declare function isCalendarIntervalLabel(label: unknown): boolean;
7
37
  /** The UTC start of the `months`-month bar holding `tsMs`, months counted from January. */
8
38
  export declare function calendarBarStartMs(tsMs: number, months: number): number;
9
- /** The start of the bar holding `tsMs`: the calendar boundary at a calendar length, else the fixed UTC floor. */
39
+ /**
40
+ * The floor of `tsMs` on the fixed grid of a chart or leg bar length, in the `%` form: `tsMs - (tsMs % intervalMs)`
41
+ * on the epoch grid, and the anchored floor from `TYPED_DAY_WEEK_GRID_ORIGIN_MS` for a typed day or week length
42
+ * (`isTypedDayWeekMs`). It is the ONE place a bar length is given its grid, so every floor of a chart or leg interval
43
+ * goes through it (or its siblings below), never through inline arithmetic. Calendar lengths are not handled here:
44
+ * `barStartMs` does that.
45
+ */
46
+ export declare function fixedGridFloorMs(tsMs: number, intervalMs: number): number;
47
+ /** `fixedGridFloorMs` in the `Math.floor` form. The two forms differ before 1970, so a site keeps the form it had. */
48
+ export declare function fixedGridFloorDivMs(tsMs: number, intervalMs: number): number;
49
+ /** `fixedGridFloorDivMs` for a time and a bar length in seconds. */
50
+ export declare function fixedGridFloorDivSec(sec: number, intervalSec: number): number;
51
+ /**
52
+ * How far `tsMs` sits past its bar's open on the fixed grid of a chart or leg bar length, in the `%` form:
53
+ * `tsMs % intervalMs` on the epoch grid, `tsMs` less the anchored floor for a typed day or week length. It keeps
54
+ * `fixedGridFloorMs(t, L) === t - fixedGridOffsetMs(t, L)` for every input, so a site that subtracts the offset itself
55
+ * (or tests it against 0 for "on the grid") rides the same grid as the floor without reordering its arithmetic.
56
+ */
57
+ export declare function fixedGridOffsetMs(tsMs: number, intervalMs: number): number;
58
+ /** `fixedGridOffsetMs` for a time and a bar length in seconds. */
59
+ export declare function fixedGridOffsetSec(sec: number, intervalSec: number): number;
60
+ /**
61
+ * The start of the period holding `tsMs` for a span that is NOT a chart or leg bar length (a profile
62
+ * session period, a holdings bucket, a fold grid): the calendar boundary at a calendar length, else the
63
+ * epoch floor. It never follows a bar grid: a 28-day period and a 4-week bar share a length, not a grid.
64
+ */
65
+ export declare function periodStartMs(tsMs: number, periodMs: number): number;
66
+ /** The start of the bar holding `tsMs`: the calendar boundary at a calendar length, else the fixed grid floor. */
10
67
  export declare function barStartMs(tsMs: number, intervalMs: number): number;
11
68
  /** When the bar opening at `startMs` closes: the next calendar boundary at a calendar length, else start + length. */
12
69
  export declare function barEndMs(startMs: number, intervalMs: number): number;
@@ -22,3 +79,28 @@ export declare function prevBarStartMs(startMs: number, intervalMs: number): num
22
79
  * candles where the average month's 30.4375 days counts 731); a bar's close is `barEndMs`.
23
80
  */
24
81
  export declare function calendarLongestBarMs(intervalMs: number): number;
82
+ /** Where the chunk grid of the chart interval `intervalMs` starts (ms): Monday 2000-01-03 for a typed day or week
83
+ * length, the epoch for every other interval. */
84
+ export declare function chunkGridOriginMs(intervalMs: number): number;
85
+ /**
86
+ * The earliest time (seconds) a window of the chart interval `intervalMs` may start: 946,857,600 (Monday 2000-01-03)
87
+ * for a typed day or week length, 0 for every other interval. It is a bar edge and a chunk edge of every typed day or
88
+ * week length, and it is positive, so an absolute window floored to it is never read as a floating window.
89
+ */
90
+ export declare function windowFloorSec(intervalMs: number): number;
91
+ /** The floor of `tsMs` on the grid of chunks `chunkMs` long of the chart interval `intervalMs` (`Math.floor` form). */
92
+ export declare function chunkFloorMs(tsMs: number, chunkMs: number, intervalMs: number): number;
93
+ /** The ceil of `tsMs` on the chunk grid of `intervalMs` (ms). */
94
+ export declare function chunkCeilMs(tsMs: number, chunkMs: number, intervalMs: number): number;
95
+ /** `chunkFloorMs` for a time and a chunk length in seconds (the grid is still keyed on `intervalMs`). */
96
+ export declare function chunkFloorSec(sec: number, chunkSec: number, intervalMs: number): number;
97
+ /** `chunkCeilMs` in seconds. */
98
+ export declare function chunkCeilSec(sec: number, chunkSec: number, intervalMs: number): number;
99
+ /**
100
+ * The floor of `sec` on the chunk grid in the `%` form (`sec - sec % chunkSec` at origin 0, toward zero before 1970).
101
+ * At a non-zero origin it is a true floor at or after the origin; before the origin it rounds toward the origin (up),
102
+ * which no planner call reaches: `windowFloorSec` keeps every window of such an interval at or after the origin.
103
+ */
104
+ export declare function chunkFloorRemSec(sec: number, chunkSec: number, intervalMs: number): number;
105
+ /** Whether `sec` lies on the chunk grid of `intervalMs` (`sec % chunkSec === 0` at origin 0). */
106
+ export declare function isOnChunkGridSec(sec: number, chunkSec: number, intervalMs: number): boolean;
@@ -12,10 +12,34 @@
12
12
  * of finer bars through `calendarLongestBarMs`.
13
13
  *
14
14
  * Keyed on the exact lengths Intervals.map_unit gives the calendar labels; any
15
- * other length (the legacy 28-day '1mm' included) is fixed-length. A leaf:
15
+ * other length is fixed-length. The 35 typed day and week lengths (2d to 20d,
16
+ * 2w to 20w) ride a fixed grid that starts on Monday 2000-01-03, the gateway's
17
+ * grid for them; every other fixed length rides the epoch grid. A leaf:
16
18
  * workers and live writers read it.
17
19
  */
18
- import { candleBarEndMs } from './candle-bar-end.util.js';
20
+ import { candleBarEndMs, isTypedDayWeekMs } from './candle-bar-end.util.js';
21
+ export { isTypedDayWeekMs };
22
+ /** Where the bar grid of a typed day or week length starts: Monday 2000-01-03 00:00 UTC (unix day 10959). */
23
+ export const TYPED_DAY_WEEK_GRID_ORIGIN_MS = 946_857_600_000;
24
+ const TYPED_DAY_WEEK_GRID_ORIGIN_SEC = TYPED_DAY_WEEK_GRID_ORIGIN_MS / 1000;
25
+ /**
26
+ * The engine's bar grid origin (`barGridOriginMs`) for a chart on `intervalMs`: Monday 2000-01-03 on a typed day or
27
+ * week interval, whose bars count from it, and absent on every other chart (the engine's epoch grid). Written on the
28
+ * live settings so it follows an interval switch both ways (refetchDataOfChart calls it on every dataset load); an
29
+ * engine that does not know the setting ignores it.
30
+ */
31
+ export function stampBarGridOrigin(settings, intervalMs) {
32
+ if (!settings)
33
+ return;
34
+ // The pinned settings typings predate the field: widened here alone.
35
+ const live = settings;
36
+ if (isTypedDayWeekMs(intervalMs))
37
+ live.barGridOriginMs = TYPED_DAY_WEEK_GRID_ORIGIN_MS;
38
+ else if ('barGridOriginMs' in live)
39
+ delete live.barGridOriginMs;
40
+ }
41
+ /** The start of the bar holding `t` on a grid of `length` from `origin`, in any one unit; correct before the origin. */
42
+ const anchoredFloor = (t, length, origin) => origin + Math.floor((t - origin) / length) * length;
19
43
  const AVERAGE_MONTH_MS = 2_629_800_000;
20
44
  const DAY_MS = 86_400_000;
21
45
  const MONTHS_BY_LENGTH = new Map([
@@ -50,10 +74,61 @@ export function calendarBarStartMs(tsMs, months) {
50
74
  const month = d.getUTCMonth();
51
75
  return Date.UTC(d.getUTCFullYear(), month - (month % months), 1);
52
76
  }
53
- /** The start of the bar holding `tsMs`: the calendar boundary at a calendar length, else the fixed UTC floor. */
77
+ /**
78
+ * The floor of `tsMs` on the fixed grid of a chart or leg bar length, in the `%` form: `tsMs - (tsMs % intervalMs)`
79
+ * on the epoch grid, and the anchored floor from `TYPED_DAY_WEEK_GRID_ORIGIN_MS` for a typed day or week length
80
+ * (`isTypedDayWeekMs`). It is the ONE place a bar length is given its grid, so every floor of a chart or leg interval
81
+ * goes through it (or its siblings below), never through inline arithmetic. Calendar lengths are not handled here:
82
+ * `barStartMs` does that.
83
+ */
84
+ export function fixedGridFloorMs(tsMs, intervalMs) {
85
+ if (isTypedDayWeekMs(intervalMs))
86
+ return anchoredFloor(tsMs, intervalMs, TYPED_DAY_WEEK_GRID_ORIGIN_MS);
87
+ return tsMs - (tsMs % intervalMs);
88
+ }
89
+ /** `fixedGridFloorMs` in the `Math.floor` form. The two forms differ before 1970, so a site keeps the form it had. */
90
+ export function fixedGridFloorDivMs(tsMs, intervalMs) {
91
+ if (isTypedDayWeekMs(intervalMs))
92
+ return anchoredFloor(tsMs, intervalMs, TYPED_DAY_WEEK_GRID_ORIGIN_MS);
93
+ return Math.floor(tsMs / intervalMs) * intervalMs;
94
+ }
95
+ /** `fixedGridFloorDivMs` for a time and a bar length in seconds. */
96
+ export function fixedGridFloorDivSec(sec, intervalSec) {
97
+ if (isTypedDayWeekMs(intervalSec * 1000))
98
+ return anchoredFloor(sec, intervalSec, TYPED_DAY_WEEK_GRID_ORIGIN_SEC);
99
+ return Math.floor(sec / intervalSec) * intervalSec;
100
+ }
101
+ /**
102
+ * How far `tsMs` sits past its bar's open on the fixed grid of a chart or leg bar length, in the `%` form:
103
+ * `tsMs % intervalMs` on the epoch grid, `tsMs` less the anchored floor for a typed day or week length. It keeps
104
+ * `fixedGridFloorMs(t, L) === t - fixedGridOffsetMs(t, L)` for every input, so a site that subtracts the offset itself
105
+ * (or tests it against 0 for "on the grid") rides the same grid as the floor without reordering its arithmetic.
106
+ */
107
+ export function fixedGridOffsetMs(tsMs, intervalMs) {
108
+ if (isTypedDayWeekMs(intervalMs))
109
+ return tsMs - anchoredFloor(tsMs, intervalMs, TYPED_DAY_WEEK_GRID_ORIGIN_MS);
110
+ return tsMs % intervalMs;
111
+ }
112
+ /** `fixedGridOffsetMs` for a time and a bar length in seconds. */
113
+ export function fixedGridOffsetSec(sec, intervalSec) {
114
+ if (isTypedDayWeekMs(intervalSec * 1000)) {
115
+ return sec - anchoredFloor(sec, intervalSec, TYPED_DAY_WEEK_GRID_ORIGIN_SEC);
116
+ }
117
+ return sec % intervalSec;
118
+ }
119
+ /**
120
+ * The start of the period holding `tsMs` for a span that is NOT a chart or leg bar length (a profile
121
+ * session period, a holdings bucket, a fold grid): the calendar boundary at a calendar length, else the
122
+ * epoch floor. It never follows a bar grid: a 28-day period and a 4-week bar share a length, not a grid.
123
+ */
124
+ export function periodStartMs(tsMs, periodMs) {
125
+ const months = calendarMonthsOfMs(periodMs);
126
+ return months === null ? tsMs - (tsMs % periodMs) : calendarBarStartMs(tsMs, months);
127
+ }
128
+ /** The start of the bar holding `tsMs`: the calendar boundary at a calendar length, else the fixed grid floor. */
54
129
  export function barStartMs(tsMs, intervalMs) {
55
130
  const months = calendarMonthsOfMs(intervalMs);
56
- return months === null ? tsMs - (tsMs % intervalMs) : calendarBarStartMs(tsMs, months);
131
+ return months === null ? fixedGridFloorMs(tsMs, intervalMs) : calendarBarStartMs(tsMs, months);
57
132
  }
58
133
  /** When the bar opening at `startMs` closes: the next calendar boundary at a calendar length, else start + length. */
59
134
  export function barEndMs(startMs, intervalMs) {
@@ -79,3 +154,76 @@ export function prevBarStartMs(startMs, intervalMs) {
79
154
  export function calendarLongestBarMs(intervalMs) {
80
155
  return LONGEST_BAR_MS.get(intervalMs) ?? intervalMs;
81
156
  }
157
+ // ── Chunk grid ──
158
+ //
159
+ // The chunk grid the gateway caches on: 250-bar buckets and 50-bar pieces of a chart interval
160
+ // (`BARS_PER_BUCKET`, `BARS_PER_PIECE` in cache-alignment.util.ts). The ONE place that decides where
161
+ // that grid starts: every floor, ceil and on-grid test of a bucket or a piece goes through these
162
+ // helpers, never through inline arithmetic (tests/structure/chunk-grid-one-rule.spec.ts counts the rest).
163
+ //
164
+ // The grid starts at the epoch for every interval but the 35 typed day and week lengths, whose bars
165
+ // and chunks count from Monday 2000-01-03 (`TYPED_DAY_WEEK_GRID_ORIGIN_MS`): a chunk is a whole number
166
+ // of bars, so every chunk edge of those lengths is a bar edge. At origin 0 each helper evaluates exactly
167
+ // the expression its sites used to write inline, so the result is bit-identical for every input
168
+ // (negative times, fractions and the sign of zero included). The `Math.floor` form and the `%` form
169
+ // differ before 1970 (one rounds down, the other toward zero), so a site keeps the form it had. They
170
+ // live in this leaf beside the bar grid, so the planner reaches them through a module it already imports.
171
+ /** Where the chunk grid of the chart interval `intervalMs` starts (ms): Monday 2000-01-03 for a typed day or week
172
+ * length, the epoch for every other interval. */
173
+ export function chunkGridOriginMs(intervalMs) {
174
+ return isTypedDayWeekMs(intervalMs) ? TYPED_DAY_WEEK_GRID_ORIGIN_MS : 0;
175
+ }
176
+ /**
177
+ * The earliest time (seconds) a window of the chart interval `intervalMs` may start: 946,857,600 (Monday 2000-01-03)
178
+ * for a typed day or week length, 0 for every other interval. It is a bar edge and a chunk edge of every typed day or
179
+ * week length, and it is positive, so an absolute window floored to it is never read as a floating window.
180
+ */
181
+ export function windowFloorSec(intervalMs) {
182
+ return chunkGridOriginMs(intervalMs) / 1000;
183
+ }
184
+ /** The floor of `tsMs` on the grid of chunks `chunkMs` long of the chart interval `intervalMs` (`Math.floor` form). */
185
+ export function chunkFloorMs(tsMs, chunkMs, intervalMs) {
186
+ const origin = chunkGridOriginMs(intervalMs);
187
+ if (origin === 0)
188
+ return Math.floor(tsMs / chunkMs) * chunkMs;
189
+ return origin + Math.floor((tsMs - origin) / chunkMs) * chunkMs;
190
+ }
191
+ /** The ceil of `tsMs` on the chunk grid of `intervalMs` (ms). */
192
+ export function chunkCeilMs(tsMs, chunkMs, intervalMs) {
193
+ const origin = chunkGridOriginMs(intervalMs);
194
+ if (origin === 0)
195
+ return Math.ceil(tsMs / chunkMs) * chunkMs;
196
+ return origin + Math.ceil((tsMs - origin) / chunkMs) * chunkMs;
197
+ }
198
+ /** `chunkFloorMs` for a time and a chunk length in seconds (the grid is still keyed on `intervalMs`). */
199
+ export function chunkFloorSec(sec, chunkSec, intervalMs) {
200
+ const origin = chunkGridOriginMs(intervalMs) / 1000;
201
+ if (origin === 0)
202
+ return Math.floor(sec / chunkSec) * chunkSec;
203
+ return origin + Math.floor((sec - origin) / chunkSec) * chunkSec;
204
+ }
205
+ /** `chunkCeilMs` in seconds. */
206
+ export function chunkCeilSec(sec, chunkSec, intervalMs) {
207
+ const origin = chunkGridOriginMs(intervalMs) / 1000;
208
+ if (origin === 0)
209
+ return Math.ceil(sec / chunkSec) * chunkSec;
210
+ return origin + Math.ceil((sec - origin) / chunkSec) * chunkSec;
211
+ }
212
+ /**
213
+ * The floor of `sec` on the chunk grid in the `%` form (`sec - sec % chunkSec` at origin 0, toward zero before 1970).
214
+ * At a non-zero origin it is a true floor at or after the origin; before the origin it rounds toward the origin (up),
215
+ * which no planner call reaches: `windowFloorSec` keeps every window of such an interval at or after the origin.
216
+ */
217
+ export function chunkFloorRemSec(sec, chunkSec, intervalMs) {
218
+ const origin = chunkGridOriginMs(intervalMs) / 1000;
219
+ if (origin === 0)
220
+ return sec - (sec % chunkSec);
221
+ return sec - ((sec - origin) % chunkSec);
222
+ }
223
+ /** Whether `sec` lies on the chunk grid of `intervalMs` (`sec % chunkSec === 0` at origin 0). */
224
+ export function isOnChunkGridSec(sec, chunkSec, intervalMs) {
225
+ const origin = chunkGridOriginMs(intervalMs) / 1000;
226
+ if (origin === 0)
227
+ return sec % chunkSec === 0;
228
+ return (sec - origin) % chunkSec === 0;
229
+ }