@jam-overture/loom 0.1.0 → 0.3.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 (414) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/audience/compose.d.ts +112 -0
  11. package/dist/audience/compose.js +134 -0
  12. package/dist/audience/memory.d.ts +14 -0
  13. package/dist/audience/memory.js +71 -0
  14. package/dist/audience/overlay-store.d.ts +343 -0
  15. package/dist/audience/overlay-store.js +217 -0
  16. package/dist/audience/rule.d.ts +121 -0
  17. package/dist/audience/rule.js +78 -0
  18. package/dist/cli/index.d.ts +3 -4
  19. package/dist/cli/index.js +3 -4
  20. package/dist/cli/templates.js +19 -0
  21. package/dist/data/adapter.d.ts +9 -1
  22. package/dist/data/adapter.js +2 -0
  23. package/dist/data/plan.js +0 -0
  24. package/dist/data/resolution.d.ts +23 -1
  25. package/dist/data/resolve.d.ts +31 -4
  26. package/dist/data/resolve.js +11 -3
  27. package/dist/ids.d.ts +10 -0
  28. package/dist/ids.js +11 -1
  29. package/dist/index.d.ts +1 -0
  30. package/dist/index.js +1 -0
  31. package/dist/interpretation/anthropic.d.ts +1 -1
  32. package/dist/interpretation/anthropic.js +2 -22
  33. package/dist/interpretation/client.d.ts +1 -1
  34. package/dist/interpretation/materialize.js +67 -22
  35. package/dist/interpretation/openai-compatible.d.ts +36 -0
  36. package/dist/interpretation/openai-compatible.js +79 -0
  37. package/dist/interpretation/status.d.ts +19 -0
  38. package/dist/interpretation/status.js +26 -0
  39. package/dist/live/index.d.ts +73 -0
  40. package/dist/live/index.js +73 -0
  41. package/dist/live/pages.d.ts +187 -0
  42. package/dist/live/pages.js +161 -0
  43. package/dist/live/pull.d.ts +147 -0
  44. package/dist/live/pull.js +398 -0
  45. package/dist/live/pulling.d.ts +79 -0
  46. package/dist/live/pulling.js +117 -0
  47. package/dist/live/window.d.ts +129 -0
  48. package/dist/live/window.js +132 -0
  49. package/dist/patch.d.ts +54 -0
  50. package/dist/patch.js +44 -0
  51. package/dist/project/closing.d.ts +51 -0
  52. package/dist/project/closing.js +53 -0
  53. package/dist/project/memory.d.ts +20 -0
  54. package/dist/project/memory.js +97 -0
  55. package/dist/project/project.d.ts +90 -0
  56. package/dist/project/project.js +91 -0
  57. package/dist/project/store.d.ts +135 -0
  58. package/dist/project/store.js +41 -0
  59. package/dist/registered.d.ts +64 -0
  60. package/dist/registered.js +118 -0
  61. package/dist/render/addressed.d.ts +35 -0
  62. package/dist/render/addressed.js +79 -0
  63. package/dist/render/behaviour-adjust.d.ts +11 -19
  64. package/dist/render/behaviour-adjust.js +75 -21
  65. package/dist/render/behaviour-present.d.ts +8 -0
  66. package/dist/render/behaviour-present.js +57 -6
  67. package/dist/render/behaviour.d.ts +98 -17
  68. package/dist/render/behaviour.js +91 -26
  69. package/dist/render/control-name.d.ts +68 -0
  70. package/dist/render/control-name.js +37 -0
  71. package/dist/render/diagnostics.d.ts +72 -0
  72. package/dist/render/diagnostics.js +7 -0
  73. package/dist/render/document-theme.d.ts +70 -0
  74. package/dist/render/document-theme.js +139 -0
  75. package/dist/render/editable.d.ts +15 -1
  76. package/dist/render/editable.js +13 -1
  77. package/dist/render/expected.d.ts +98 -0
  78. package/dist/render/expected.js +88 -0
  79. package/dist/render/index.d.ts +4 -0
  80. package/dist/render/index.js +4 -0
  81. package/dist/render/reads.d.ts +11 -0
  82. package/dist/render/reads.js +12 -1
  83. package/dist/render/render.d.ts +11 -0
  84. package/dist/render/render.js +294 -53
  85. package/dist/render/request.d.ts +8 -1
  86. package/dist/render/request.js +1 -0
  87. package/dist/render/slots.d.ts +52 -0
  88. package/dist/render/slots.js +24 -0
  89. package/dist/render/theme.d.ts +54 -1
  90. package/dist/render/theme.js +23 -1
  91. package/dist/render/unshown.d.ts +152 -0
  92. package/dist/render/unshown.js +80 -0
  93. package/dist/runtime/analysis.d.ts +94 -9
  94. package/dist/runtime/analysis.js +54 -9
  95. package/dist/runtime/assessment.d.ts +36 -2
  96. package/dist/runtime/assessment.js +27 -2
  97. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  98. package/dist/runtime/auto-apply-ceiling.js +66 -0
  99. package/dist/runtime/checks.d.ts +148 -0
  100. package/dist/runtime/checks.js +112 -0
  101. package/dist/runtime/disposition.d.ts +96 -0
  102. package/dist/runtime/disposition.js +46 -0
  103. package/dist/runtime/gate.js +91 -10
  104. package/dist/runtime/index.d.ts +4 -0
  105. package/dist/runtime/index.js +4 -0
  106. package/dist/runtime/irreversibility.d.ts +64 -0
  107. package/dist/runtime/irreversibility.js +45 -0
  108. package/dist/runtime/nesting.d.ts +13 -1
  109. package/dist/runtime/nesting.js +41 -24
  110. package/dist/runtime/pipeline.d.ts +43 -0
  111. package/dist/runtime/pipeline.js +10 -2
  112. package/dist/runtime/policy-change.d.ts +93 -0
  113. package/dist/runtime/policy-change.js +305 -0
  114. package/dist/runtime/policy-log.d.ts +406 -0
  115. package/dist/runtime/policy-log.js +285 -0
  116. package/dist/runtime/policy.d.ts +8 -6
  117. package/dist/runtime/policy.js +5 -2
  118. package/dist/runtime/repointing.js +0 -0
  119. package/dist/runtime/reversibility.d.ts +11 -9
  120. package/dist/runtime/stakes.d.ts +129 -1
  121. package/dist/runtime/stakes.js +240 -26
  122. package/dist/runtime/vocabulary.d.ts +164 -7
  123. package/dist/runtime/vocabulary.js +181 -8
  124. package/dist/sdk/audit.d.ts +174 -3
  125. package/dist/sdk/audit.js +176 -17
  126. package/dist/sdk/catalogue.d.ts +9 -1
  127. package/dist/sdk/conformance.d.ts +37 -3
  128. package/dist/sdk/conformance.js +25 -4
  129. package/dist/sdk/definition.d.ts +129 -5
  130. package/dist/sdk/definition.js +66 -0
  131. package/dist/sdk/registry.d.ts +45 -2
  132. package/dist/sdk/registry.js +102 -1
  133. package/dist/signals/acted.contract.d.ts +21 -0
  134. package/dist/signals/acted.contract.js +236 -0
  135. package/dist/signals/acted.d.ts +359 -0
  136. package/dist/signals/acted.js +135 -0
  137. package/dist/signals/action-change.d.ts +507 -0
  138. package/dist/signals/action-change.js +265 -0
  139. package/dist/signals/action.d.ts +331 -0
  140. package/dist/signals/action.js +182 -0
  141. package/dist/signals/agenda.d.ts +585 -0
  142. package/dist/signals/agenda.js +295 -0
  143. package/dist/signals/applied-window.contract.d.ts +23 -0
  144. package/dist/signals/applied-window.contract.js +160 -0
  145. package/dist/signals/arrivals.contract.d.ts +21 -0
  146. package/dist/signals/arrivals.contract.js +180 -0
  147. package/dist/signals/arrivals.d.ts +375 -0
  148. package/dist/signals/arrivals.js +254 -0
  149. package/dist/signals/arriving.d.ts +210 -0
  150. package/dist/signals/arriving.js +133 -0
  151. package/dist/signals/audiences.d.ts +528 -0
  152. package/dist/signals/audiences.js +255 -0
  153. package/dist/signals/broadcast.d.ts +33 -17
  154. package/dist/signals/broadcast.js +255 -32
  155. package/dist/signals/change.d.ts +378 -0
  156. package/dist/signals/change.js +327 -0
  157. package/dist/signals/collect.d.ts +169 -34
  158. package/dist/signals/collect.js +186 -38
  159. package/dist/signals/conversion.d.ts +348 -0
  160. package/dist/signals/conversion.js +235 -0
  161. package/dist/signals/copy-change.d.ts +553 -0
  162. package/dist/signals/copy-change.js +377 -0
  163. package/dist/signals/copy.d.ts +337 -0
  164. package/dist/signals/copy.js +211 -0
  165. package/dist/signals/correlated.contract.d.ts +24 -0
  166. package/dist/signals/correlated.contract.js +94 -0
  167. package/dist/signals/counters.d.ts +97 -0
  168. package/dist/signals/counters.js +160 -0
  169. package/dist/signals/deliver.d.ts +23 -4
  170. package/dist/signals/deliver.js +34 -6
  171. package/dist/signals/deployment-change.d.ts +395 -0
  172. package/dist/signals/deployment-change.js +309 -0
  173. package/dist/signals/deployment.d.ts +278 -0
  174. package/dist/signals/deployment.js +178 -0
  175. package/dist/signals/door.d.ts +114 -0
  176. package/dist/signals/door.js +77 -0
  177. package/dist/signals/expire.d.ts +192 -0
  178. package/dist/signals/expire.js +213 -0
  179. package/dist/signals/fold.d.ts +10 -0
  180. package/dist/signals/fold.js +5 -1
  181. package/dist/signals/form-action.d.ts +302 -0
  182. package/dist/signals/form-action.js +169 -0
  183. package/dist/signals/form-copy.d.ts +523 -0
  184. package/dist/signals/form-copy.js +346 -0
  185. package/dist/signals/forms.d.ts +247 -0
  186. package/dist/signals/forms.js +147 -0
  187. package/dist/signals/frontier.d.ts +268 -0
  188. package/dist/signals/frontier.js +145 -0
  189. package/dist/signals/funnel-change.d.ts +548 -0
  190. package/dist/signals/funnel-change.js +361 -0
  191. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  192. package/dist/signals/funnel-hours.contract.js +221 -0
  193. package/dist/signals/funnel-hours.d.ts +293 -0
  194. package/dist/signals/funnel-hours.js +99 -0
  195. package/dist/signals/funnel.d.ts +592 -0
  196. package/dist/signals/funnel.js +231 -0
  197. package/dist/signals/health.d.ts +694 -0
  198. package/dist/signals/health.js +573 -0
  199. package/dist/signals/index.d.ts +60 -0
  200. package/dist/signals/index.js +60 -0
  201. package/dist/signals/ingest.d.ts +56 -1
  202. package/dist/signals/ingest.js +91 -1
  203. package/dist/signals/inside.d.ts +190 -0
  204. package/dist/signals/inside.js +263 -0
  205. package/dist/signals/join.d.ts +56 -0
  206. package/dist/signals/join.js +60 -0
  207. package/dist/signals/journal.d.ts +123 -9
  208. package/dist/signals/kept.contract.d.ts +22 -0
  209. package/dist/signals/kept.contract.js +111 -0
  210. package/dist/signals/kinds.d.ts +8 -6
  211. package/dist/signals/kinds.js +14 -6
  212. package/dist/signals/library-action.d.ts +430 -0
  213. package/dist/signals/library-action.js +336 -0
  214. package/dist/signals/library-agenda-change.d.ts +324 -0
  215. package/dist/signals/library-agenda-change.js +199 -0
  216. package/dist/signals/library-agenda.d.ts +258 -0
  217. package/dist/signals/library-agenda.js +167 -0
  218. package/dist/signals/library-change.d.ts +477 -0
  219. package/dist/signals/library-change.js +335 -0
  220. package/dist/signals/library-copy-change.d.ts +498 -0
  221. package/dist/signals/library-copy-change.js +476 -0
  222. package/dist/signals/library-pace.d.ts +319 -0
  223. package/dist/signals/library-pace.js +305 -0
  224. package/dist/signals/library-reach-change.d.ts +646 -0
  225. package/dist/signals/library-reach-change.js +542 -0
  226. package/dist/signals/library-reach.d.ts +377 -0
  227. package/dist/signals/library-reach.js +227 -0
  228. package/dist/signals/library-senders-change.d.ts +457 -0
  229. package/dist/signals/library-senders-change.js +367 -0
  230. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  231. package/dist/signals/library-senders-reach-change.js +538 -0
  232. package/dist/signals/library-senders-reach.d.ts +340 -0
  233. package/dist/signals/library-senders-reach.js +252 -0
  234. package/dist/signals/library-senders.d.ts +271 -0
  235. package/dist/signals/library-senders.js +180 -0
  236. package/dist/signals/library-word-reach-change.d.ts +567 -0
  237. package/dist/signals/library-word-reach-change.js +564 -0
  238. package/dist/signals/library.d.ts +306 -0
  239. package/dist/signals/library.js +178 -0
  240. package/dist/signals/memory.d.ts +9 -0
  241. package/dist/signals/memory.js +246 -14
  242. package/dist/signals/migrate.d.ts +20 -4
  243. package/dist/signals/migrate.js +269 -8
  244. package/dist/signals/notice.d.ts +389 -0
  245. package/dist/signals/notice.js +250 -0
  246. package/dist/signals/pace-change.d.ts +501 -0
  247. package/dist/signals/pace-change.js +310 -0
  248. package/dist/signals/pace.d.ts +296 -0
  249. package/dist/signals/pace.js +291 -0
  250. package/dist/signals/page-views.d.ts +365 -0
  251. package/dist/signals/page-views.js +218 -0
  252. package/dist/signals/part-pace.d.ts +378 -0
  253. package/dist/signals/part-pace.js +333 -0
  254. package/dist/signals/parts.d.ts +354 -0
  255. package/dist/signals/parts.js +232 -0
  256. package/dist/signals/postgres.d.ts +16 -2
  257. package/dist/signals/postgres.js +753 -76
  258. package/dist/signals/progress.d.ts +212 -0
  259. package/dist/signals/progress.js +150 -0
  260. package/dist/signals/ratios.d.ts +108 -0
  261. package/dist/signals/ratios.js +40 -0
  262. package/dist/signals/reach.d.ts +309 -0
  263. package/dist/signals/reach.js +93 -0
  264. package/dist/signals/readable.d.ts +34 -0
  265. package/dist/signals/readable.js +34 -0
  266. package/dist/signals/readership.d.ts +381 -0
  267. package/dist/signals/readership.js +308 -0
  268. package/dist/signals/region-pages.d.ts +173 -0
  269. package/dist/signals/region-pages.js +62 -0
  270. package/dist/signals/region.d.ts +287 -0
  271. package/dist/signals/region.js +198 -0
  272. package/dist/signals/retention.d.ts +163 -0
  273. package/dist/signals/retention.js +75 -0
  274. package/dist/signals/rhythm.d.ts +302 -0
  275. package/dist/signals/rhythm.js +262 -0
  276. package/dist/signals/rollup.d.ts +194 -4
  277. package/dist/signals/rollup.js +0 -0
  278. package/dist/signals/schema.d.ts +1069 -1
  279. package/dist/signals/schema.js +393 -3
  280. package/dist/signals/signal.d.ts +237 -11
  281. package/dist/signals/signal.js +70 -10
  282. package/dist/signals/silence-census.d.ts +205 -0
  283. package/dist/signals/silence-census.js +87 -0
  284. package/dist/signals/silences.d.ts +1147 -0
  285. package/dist/signals/silences.js +996 -0
  286. package/dist/signals/subtrees.d.ts +123 -0
  287. package/dist/signals/subtrees.js +102 -0
  288. package/dist/signals/tally.d.ts +262 -12
  289. package/dist/signals/unread.d.ts +292 -0
  290. package/dist/signals/unread.js +137 -0
  291. package/dist/signals/window-agenda.d.ts +276 -0
  292. package/dist/signals/window-agenda.js +83 -0
  293. package/dist/signals/window-figures.d.ts +148 -0
  294. package/dist/signals/window-figures.js +42 -0
  295. package/dist/signals/window-funnels.d.ts +88 -0
  296. package/dist/signals/window-funnels.js +47 -0
  297. package/dist/signals/window.d.ts +866 -0
  298. package/dist/signals/window.js +693 -0
  299. package/dist/signals/words.d.ts +24 -0
  300. package/dist/signals/words.js +24 -0
  301. package/dist/store/cache.d.ts +101 -0
  302. package/dist/store/cache.js +149 -0
  303. package/dist/store/history.d.ts +82 -0
  304. package/dist/store/history.js +36 -0
  305. package/dist/store/index.d.ts +30 -0
  306. package/dist/store/index.js +30 -0
  307. package/dist/store/memory.d.ts +2 -1
  308. package/dist/store/memory.js +48 -12
  309. package/dist/store/migrate.d.ts +106 -0
  310. package/dist/store/migrate.js +323 -7
  311. package/dist/store/postgres-applications.d.ts +4 -0
  312. package/dist/store/postgres-applications.js +197 -0
  313. package/dist/store/postgres-audience.d.ts +14 -0
  314. package/dist/store/postgres-audience.js +272 -0
  315. package/dist/store/postgres-holds.d.ts +10 -1
  316. package/dist/store/postgres-holds.js +116 -101
  317. package/dist/store/postgres-policy-log.d.ts +14 -0
  318. package/dist/store/postgres-policy-log.js +240 -0
  319. package/dist/store/postgres-projects.d.ts +4 -0
  320. package/dist/store/postgres-projects.js +217 -0
  321. package/dist/store/postgres.d.ts +17 -1
  322. package/dist/store/postgres.js +60 -9
  323. package/dist/store/replay.d.ts +102 -1
  324. package/dist/store/replay.js +190 -19
  325. package/dist/store/reseed.d.ts +238 -0
  326. package/dist/store/reseed.js +308 -0
  327. package/dist/store/schema.d.ts +762 -2
  328. package/dist/store/schema.js +218 -5
  329. package/dist/store/source.d.ts +57 -1
  330. package/dist/store/source.js +65 -1
  331. package/dist/store/store.d.ts +29 -6
  332. package/dist/submit/resolve.d.ts +1 -1
  333. package/dist/submit/resolve.js +2 -1
  334. package/dist/telemetry/calibration.d.ts +25 -0
  335. package/dist/telemetry/calibration.js +27 -1
  336. package/dist/telemetry/event.d.ts +391 -33
  337. package/dist/telemetry/event.js +84 -20
  338. package/dist/telemetry/index.d.ts +2 -0
  339. package/dist/telemetry/index.js +2 -0
  340. package/dist/telemetry/journal.d.ts +104 -3
  341. package/dist/telemetry/journal.js +9 -0
  342. package/dist/telemetry/lookup.d.ts +27 -0
  343. package/dist/telemetry/lookup.js +18 -0
  344. package/dist/telemetry/memory.js +33 -1
  345. package/dist/telemetry/migrate.js +22 -1
  346. package/dist/telemetry/postgres.d.ts +10 -1
  347. package/dist/telemetry/postgres.js +188 -90
  348. package/dist/telemetry/remeasure.d.ts +78 -0
  349. package/dist/telemetry/remeasure.js +83 -0
  350. package/dist/telemetry/retention.d.ts +2 -2
  351. package/dist/telemetry/schema.d.ts +17 -0
  352. package/dist/telemetry/schema.js +27 -1
  353. package/dist/telemetry/sink.d.ts +2 -2
  354. package/dist/telemetry/window.d.ts +135 -0
  355. package/dist/telemetry/window.js +101 -0
  356. package/dist/testing/application-contract.d.ts +14 -0
  357. package/dist/testing/application-contract.js +270 -0
  358. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  359. package/dist/testing/audience-overlay-contract.js +354 -0
  360. package/dist/testing/contracts.d.ts +13 -7
  361. package/dist/testing/contracts.js +13 -7
  362. package/dist/testing/definitions.d.ts +78 -0
  363. package/dist/testing/definitions.js +134 -9
  364. package/dist/testing/doubles.d.ts +103 -0
  365. package/dist/testing/doubles.js +143 -0
  366. package/dist/testing/index.d.ts +2 -2
  367. package/dist/testing/index.js +2 -2
  368. package/dist/testing/journal-contract.js +297 -6
  369. package/dist/testing/model-contract.d.ts +110 -0
  370. package/dist/testing/model-contract.js +150 -0
  371. package/dist/testing/policy-log-contract.d.ts +26 -0
  372. package/dist/testing/policy-log-contract.js +344 -0
  373. package/dist/testing/project-contract.d.ts +14 -0
  374. package/dist/testing/project-contract.js +266 -0
  375. package/dist/testing/reader-signal-contract.d.ts +27 -2
  376. package/dist/testing/reader-signal-contract.js +475 -5
  377. package/dist/testing/store-contract.d.ts +7 -1
  378. package/dist/testing/store-contract.js +84 -3
  379. package/dist/theme/apply.d.ts +20 -1
  380. package/dist/theme/apply.js +5 -3
  381. package/dist/theme/contrast.d.ts +19 -14
  382. package/dist/theme/contrast.js +181 -17
  383. package/dist/theme/derive.d.ts +22 -0
  384. package/dist/theme/derive.js +54 -1
  385. package/dist/theme/library.js +1 -1
  386. package/dist/theme/measure.d.ts +34 -0
  387. package/dist/theme/measure.js +30 -1
  388. package/dist/theme/palettes.js +7 -7
  389. package/dist/theme/ramp.d.ts +64 -0
  390. package/dist/theme/ramp.js +114 -0
  391. package/dist/theme/registry.d.ts +9 -0
  392. package/dist/theme/registry.js +11 -1
  393. package/dist/theme/separation.d.ts +97 -3
  394. package/dist/theme/separation.js +75 -0
  395. package/dist/tree/apply.js +13 -0
  396. package/dist/tree/compare.d.ts +9 -0
  397. package/dist/tree/compare.js +18 -0
  398. package/dist/tree/mutation.d.ts +18 -0
  399. package/dist/tree/mutation.js +24 -12
  400. package/dist/tree/navigation.d.ts +5 -0
  401. package/dist/tree/navigation.js +32 -10
  402. package/dist/tree/outline.d.ts +7 -0
  403. package/dist/tree/outline.js +9 -5
  404. package/dist/write/computed.d.ts +60 -0
  405. package/dist/write/computed.js +61 -0
  406. package/dist/write/held.d.ts +59 -0
  407. package/dist/write/index.d.ts +5 -2
  408. package/dist/write/index.js +5 -2
  409. package/dist/write/reseed.d.ts +151 -0
  410. package/dist/write/reseed.js +184 -0
  411. package/dist/write/revert.js +2 -16
  412. package/package.json +25 -3
  413. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  414. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Judge one expiry sweep's own evidence against the ceiling its deployment
3
+ * publishes.
4
+ *
5
+ * The retention is taken whole — the same `Pick` of the notice the reader's
6
+ * sentence is built from (0320) — so the ceiling judged here is the ceiling
7
+ * published, by construction rather than by a reviewer.
8
+ *
9
+ * **An unstated interval wins over everything else**, including a buffer months
10
+ * behind. It is not that the buffer is fine; it is that no ceiling was
11
+ * published, so a run has no claim of its deployment's to measure. The operator
12
+ * hears about an unstated schedule from the setting, which is where the remedy
13
+ * is.
14
+ *
15
+ * **A delivery received in the future is kept, by the same subtraction rather
16
+ * than by a special case** — a negative age is never longer than a positive
17
+ * ceiling, which is how the stall check answers a clock that disagrees with
18
+ * itself (0274).
19
+ */
20
+ export const retentionPromiseOf = (outcome, retention) => {
21
+ if (retention.sweep.state !== "stated")
22
+ return { state: "unpromised" };
23
+ const { goneWithinMs } = retention.sweep;
24
+ if (outcome.outcome === "refused" || outcome.outcome === "unavailable") {
25
+ return { state: "unread" };
26
+ }
27
+ /**
28
+ * A run that deleted nothing and read nothing saw no delivery at all, which
29
+ * is an empty table rather than a proof about one. Both answer *nothing here
30
+ * can be past the ceiling*, so the one with no figure is `unripe` beside the
31
+ * one whose figure is young — the distinction a reading of this would draw
32
+ * between them is one neither of them supports.
33
+ */
34
+ const { oldestMs } = outcome;
35
+ if (oldestMs === null)
36
+ return { state: "unripe" };
37
+ if (!Number.isFinite(oldestMs))
38
+ return { state: "unread" };
39
+ return oldestMs > goneWithinMs
40
+ ? {
41
+ state: "broken",
42
+ oldestMs,
43
+ goneWithinMs,
44
+ byMs: oldestMs - goneWithinMs,
45
+ uncounted: outcome.stopped === "uncounted",
46
+ }
47
+ : { state: "kept", oldestMs, goneWithinMs };
48
+ };
49
+ /**
50
+ * One line for the operator who runs the sweep, because they are the only
51
+ * person who can close the gap.
52
+ *
53
+ * Milliseconds, as the settings an operator typed are in: a line that rounded
54
+ * to minutes would not tell somebody who wrote an interval in the wrong units
55
+ * which units it wanted.
56
+ */
57
+ export const describeRetentionPromise = (promise) => {
58
+ switch (promise.state) {
59
+ case "unpromised":
60
+ return "readers are promised no ceiling on how long a delivery lives, so there is none for this run to keep";
61
+ case "unread":
62
+ return "no delivery was read, so nothing here says whether the ceiling readers are promised is being kept";
63
+ case "unripe":
64
+ return "nothing kept is old enough to delete, so no delivery is past the ceiling readers are promised";
65
+ case "kept":
66
+ return `the oldest delivery kept is ${promise.oldestMs}ms old, and readers are promised one is gone within ${promise.goneWithinMs}ms of arriving`;
67
+ case "broken":
68
+ return (`the oldest delivery kept is ${promise.oldestMs}ms old and readers are promised one is gone within ${promise.goneWithinMs}ms of arriving, ` +
69
+ `so that promise has been false for ${promise.byMs}ms: ` +
70
+ (promise.uncounted
71
+ ? "no fold has counted it, so nothing may delete it and the remedy is to run collection"
72
+ : "this deployment is sweeping less often than it stated, or not at all"));
73
+ }
74
+ };
75
+ //# sourceMappingURL=retention.js.map
@@ -0,0 +1,302 @@
1
+ import type { ActedSeries } from "./acted.js";
2
+ import { type ArrivalRange, type ArrivalSeries } from "./arrivals.js";
3
+ /**
4
+ * **The two ways a month of hours can be drawn, and the one of them that is a
5
+ * question nothing else here asks.**
6
+ *
7
+ * Page views are counted under the hour they began in
8
+ * ([0356](../../decisions/0356-page-views-are-counted-under-the-hour-they-began-in-as-a-sixth-counter-written-at-the-door.md))
9
+ * and what readers did under the hour they did it in
10
+ * ([0362](../../decisions/0362-what-readers-did-is-counted-under-the-hour-they-did-it-in-as-a-seventh-counter-the-fold-writes-for-the-three-delegated-kinds.md)).
11
+ * Both are read over a range as a dense hourly series, and
12
+ * [`arrivals.ts`](arrivals.ts)' `hourlySeriesOf` spells the honesty rule those
13
+ * two share: an hour with no row is a nought that is drawn, an hour before
14
+ * counting began is not drawn at all, and the hour in progress is marked rather
15
+ * than drawn as a fall.
16
+ *
17
+ * ## An hour is the unit the counter holds and not the unit a screen can draw
18
+ *
19
+ * `portal-wireframes.md` *1 · Signals* offers a range picker of **last 24
20
+ * hours, 7 days, 30 days** over a bar chart of page views. The first is 24
21
+ * bars. The third is **720**, and a screen handed 720 bars either draws them a
22
+ * third of a pixel wide or buckets them itself — and a surface bucketing them
23
+ * itself is the rule above spelled a third time, in a route group, by whoever
24
+ * is drawing the chart that week.
25
+ *
26
+ * So the fold belongs here, where the counters are read: {@link daySeriesOf}
27
+ * gives the same range as **30 bars**, and a day that the range or the clock
28
+ * cut short is marked rather than drawn as a quiet Sunday.
29
+ *
30
+ * ## The other fold answers a question no counter here has been asked
31
+ *
32
+ * A run of hours answers *how many readers arrived, and when* once. Folded the
33
+ * other way — every 09:00 of a range summed together — it answers **what a
34
+ * reader's day looks like on this deployment**: when they come, and when nobody
35
+ * does. {@link dayShapeOf} is 24 bars whatever the range, and it is the figure
36
+ * behind two questions an operator actually has: *when are my readers here*,
37
+ * and *when can I publish a change without anybody reading the page as it
38
+ * moves*.
39
+ *
40
+ * Nothing new is collected, stored or sent for either of them. Both are pure
41
+ * functions of a series a caller already holds, and the browser is not involved
42
+ * at any payload: the hour was derived at the door from the instant the request
43
+ * arrived, which is the one clock in this subsystem a page cannot move
44
+ * ([0355](../../decisions/0355-the-events-a-screen-lists-are-one-row-per-signal-and-one-page-view-is-read-on-a-key-the-caller-already-holds.md)).
45
+ *
46
+ * ## Why the shape cannot be drawn from the counts
47
+ *
48
+ * A range is hour-aligned and almost never a whole number of days, so **the
49
+ * hours of the day do not rest on the same number of days**. *Last 7 days* read
50
+ * at 09:30 holds eight 09:00s and seven 03:00s, so a shape drawn from the sums
51
+ * says readers come at 09:00 — one eighth of which is that there is one more
52
+ * 09:00 in the range. It is the plausible-false figure again: right shape,
53
+ * moves with the traffic, and wrong by a day's worth of one bar.
54
+ *
55
+ * So {@link DayHour} publishes `days` beside `count`, and the comparable figure
56
+ * is {@link DayHour.perDay} — the mean over the days that could speak for that
57
+ * hour. {@link DayShape.even} says whether the raw counts may be compared
58
+ * directly, which they may only when the range is a whole number of days.
59
+ *
60
+ * ## An hour no day could speak for is withheld and never nought
61
+ *
62
+ * *Nobody reads this page at 03:00* and *this range holds no finished 03:00* are
63
+ * one bar apart on a chart and opposite answers. The first is a measurement; the
64
+ * second is a range too short, or a deployment that began counting this morning.
65
+ * `perDay` is **absent** for the second, where every other reading in this
66
+ * subsystem withholds rather than zeroes (0301, 0326), and
67
+ * {@link quietestHoursIn} will not name an hour nothing was observed in — which
68
+ * is the one way this reading could recommend a deploy window off no evidence.
69
+ *
70
+ * ## Only whole hours reach the shape, and the arithmetic says so
71
+ *
72
+ * The hour in progress holds part of an hour's traffic, so averaging it into its
73
+ * hour of the day understates that hour by however much of it is left. It is
74
+ * left out of both the numerator and the day count, and what it held is
75
+ * published as {@link DayShape.incomplete} rather than dropped — so
76
+ * `count + incomplete` is the figure the range's own series publishes, and a
77
+ * screen that wants to say so can.
78
+ *
79
+ * The day series does the opposite with the same honesty: a partial day **keeps
80
+ * its count**, because what happened in it happened, and carries
81
+ * {@link DayBucket.hours} and {@link DayBucket.whole} so a bar nobody has
82
+ * finished arriving in is not drawn like the twenty-nine before it. The sum over
83
+ * the days is the sum over the hours, always, which is asserted rather than
84
+ * argued.
85
+ *
86
+ * ## Counts add and days do not
87
+ *
88
+ * Both folds take occurrences by addition and denominators by distinctness,
89
+ * which is the rule the hourly counters were built under: *occurrences add,
90
+ * distinctness does not* (0362). An hour handed over twice adds its count twice
91
+ * and is one hour of one day either way — the fault worth guarding, because
92
+ * counting the same thing twice in a denominator is permanent
93
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
94
+ *
95
+ * The input is a **series** and not a store's rows, and the type is what says
96
+ * so: a row of either hourly table names a tree, a revision and an audience, so
97
+ * three of them can name one hour, and only a series has been through the fold
98
+ * that makes an hour unique. `whole` is the field no row carries and every
99
+ * series does, so the mistake does not typecheck.
100
+ *
101
+ * ## The offset is a fixed number of hours and is not a time zone
102
+ *
103
+ * Both counters bucket by UTC hour, so a deployment whose readers are all in one
104
+ * country has its whole day shifted — a nine-o'clock peak in California arrives
105
+ * here as a 17:00 bar. {@link RhythmOptions.offsetHours} shifts where the day is
106
+ * cut and what each hour of the day is called, and it is **whole hours, applied
107
+ * flatly**: an hour bucket cannot be divided, so a zone at a half-hour offset is
108
+ * not nameable from these counters at all, and a zone that observes summer time
109
+ * is named by one offset or the other and is an hour out for the rest of the
110
+ * range. A screen drawing a local day says which offset it drew, which is why
111
+ * both readings publish it back.
112
+ */
113
+ /** A day, in the unit the counters are kept in. The prefix is `ARRIVAL_HOUR_MS`'. */
114
+ export declare const ARRIVAL_DAY_MS = 86400000;
115
+ /** How many hours a day of these counters has, which is what a shape has bars. */
116
+ export declare const HOURS_IN_DAY = 24;
117
+ /** What either fold may be told, which is where the reader's midnight is. */
118
+ export type RhythmOptions = {
119
+ /**
120
+ * Whole hours to add to UTC before the day is cut and its hours are named.
121
+ *
122
+ * Absent is UTC, which is what the counters hold. A fraction is truncated and
123
+ * an offset beyond a day is taken modulo one, because neither names a zone and
124
+ * both would otherwise move a bar's label by a whole day.
125
+ */
126
+ readonly offsetHours?: number;
127
+ };
128
+ /**
129
+ * One day of a range, which is one bar.
130
+ *
131
+ * Partial days are kept and marked rather than dropped: the range's first and
132
+ * last day are usually partial, a caller who handed in a clock has every day
133
+ * after it partial too, and a deployment that began counting mid-day has one
134
+ * more. A screen draws the whole ones solid and says *so far* about the rest.
135
+ */
136
+ export type DayBucket = {
137
+ /** The instant the day began, at this series' offset. */
138
+ readonly day: number;
139
+ /** What was counted in it, partial hours included. */
140
+ readonly count: number;
141
+ /** How many of its twenty-four hours the series could speak for. */
142
+ readonly hours: number;
143
+ /** Whether all twenty-four are present and every one of them over. */
144
+ readonly whole: boolean;
145
+ };
146
+ /** An hourly series folded into its days. */
147
+ export type DaySeries = {
148
+ /** The range the series was taken over, carried through unchanged. */
149
+ readonly range: ArrivalRange;
150
+ /**
151
+ * One entry per day, ascending, dense.
152
+ *
153
+ * Dense because the series it is folded from is: a day nobody arrived in is
154
+ * present with `count: 0`, and a day before counting began is not present at
155
+ * all. Empty where the series is.
156
+ */
157
+ readonly days: readonly DayBucket[];
158
+ /** The sum over the days, which is the sum over the hours they were folded from. */
159
+ readonly count: number;
160
+ /** The offset the days were cut at, in whole hours from UTC. */
161
+ readonly offsetHours: number;
162
+ /** Whether the range begins before counting did, carried through from the series. */
163
+ readonly clipped: boolean;
164
+ /** How many of the days above are not whole, which is the two edges and whatever a clock cut. */
165
+ readonly partial: number;
166
+ };
167
+ /** One hour of the day, over every day of a range. */
168
+ export type DayHour = {
169
+ /** The hour of the day, 0 to 23, at this shape's offset. */
170
+ readonly hour: number;
171
+ /** How many days contributed a whole hour here. */
172
+ readonly days: number;
173
+ /** What was counted in those hours, which is nought where no day could speak. */
174
+ readonly count: number;
175
+ /**
176
+ * The mean over the days that could speak for this hour.
177
+ *
178
+ * **Withheld rather than nought where none could**, which is the distinction
179
+ * the whole reading turns on: an hour this range holds no finished instance of
180
+ * is not an hour nobody reads in.
181
+ */
182
+ readonly perDay?: number;
183
+ };
184
+ /** Why a shape has nothing to say about any hour of the day. */
185
+ export type DayShapeSilence =
186
+ /** Nothing has ever been counted in this scope, so the series it folds is empty. */
187
+ "unmeasured"
188
+ /**
189
+ * The range holds hours and not one of them is over.
190
+ *
191
+ * A range shorter than an hour, or one read with a clock inside its own first
192
+ * hour. Counting is working and the shape is one hour away from existing.
193
+ */
194
+ | "unsettled";
195
+ /**
196
+ * The members, published so that the set can be enumerated rather than
197
+ * remembered.
198
+ *
199
+ * Every other silence set in this subsystem publishes one, and the census over
200
+ * them ([`silences.ts`](silences.ts)) is built by mapping each set's members
201
+ * through its own `meaningOf` — so a set with no published members is a set a
202
+ * census can only reach by hand, which is how this one stayed outside it for
203
+ * three days. `silence-sweep.test.ts` now fails on a set that publishes none.
204
+ */
205
+ export declare const DAY_SHAPE_SILENCES: readonly DayShapeSilence[];
206
+ /**
207
+ * One line per silence, for a surface saying why a day has no shape.
208
+ *
209
+ * **The only one of the four written for 0407 that is new text**, because this
210
+ * reading publishes no standing for the sentence to have already been in. Both
211
+ * members resolve themselves and the sentences say how, since the two remedies
212
+ * are a week apart: one wants readers, the other wants the hour to end.
213
+ */
214
+ export declare const describeDayShapeSilence: (silence: DayShapeSilence) => string;
215
+ /**
216
+ * The hours of a reader's day on this deployment, over whatever range was read.
217
+ *
218
+ * Twenty-four entries always, so a chart has a bar per hour whether or not the
219
+ * range reached it. Which of them mean anything is {@link DayHour.perDay}'s
220
+ * presence, and {@link silence} is there where none of them do.
221
+ */
222
+ export type DayShape = {
223
+ /** Twenty-four entries, ascending from hour 0. */
224
+ readonly hours: readonly DayHour[];
225
+ /** What was counted into the shape: the range's whole hours, summed. */
226
+ readonly count: number;
227
+ /**
228
+ * What the range counted and the shape left out, because the hour was not over.
229
+ *
230
+ * `count + incomplete` is the figure the series publishes for the range, so a
231
+ * screen can say *and 41 more in the hour you are in*.
232
+ */
233
+ readonly incomplete: number;
234
+ /** How many days contributed any whole hour at all. */
235
+ readonly days: number;
236
+ /**
237
+ * Whether every hour of the day rests on the same number of days.
238
+ *
239
+ * True only where the range is a whole number of days. False is the ordinary
240
+ * case and the reason {@link DayHour.perDay} exists.
241
+ */
242
+ readonly even: boolean;
243
+ /** The offset the hours were named at, in whole hours from UTC. */
244
+ readonly offsetHours: number;
245
+ /** Why there is nothing to read, where there is nothing. */
246
+ readonly silence?: DayShapeSilence;
247
+ };
248
+ /** The two fields a fold needs of a series, whichever counter it is of. */
249
+ type HourlyReading<Hour> = {
250
+ readonly range: ArrivalRange;
251
+ readonly hours: readonly Hour[];
252
+ readonly clipped: boolean;
253
+ };
254
+ /** The shape of an hour of any series this folds: the instant, and whether it is over. */
255
+ type SeriesHour = {
256
+ readonly hour: number;
257
+ readonly whole: boolean;
258
+ };
259
+ /**
260
+ * An hourly series folded into its days.
261
+ *
262
+ * Generic over the hour because the two hourly readings spell their number
263
+ * differently — `views` on an arrival hour, `count` on an acted one — and
264
+ * {@link arrivalDaysOf} and {@link actedDaysOf} are the two callers that
265
+ * exist, so no surface writes the accessor.
266
+ */
267
+ export declare const daySeriesOf: <Hour extends SeriesHour>(series: HourlyReading<Hour>, count: (hour: Hour) => number, options?: RhythmOptions) => DaySeries;
268
+ /**
269
+ * The hours of the day a series' whole hours fell in.
270
+ *
271
+ * Generic for {@link daySeriesOf}'s reason, with {@link arrivalDayShapeOf} and
272
+ * {@link actedDayShapeOf} as the two callers that exist.
273
+ */
274
+ export declare const dayShapeOf: <Hour extends SeriesHour>(series: HourlyReading<Hour>, count: (hour: Hour) => number, options?: RhythmOptions) => DayShape;
275
+ /** Page views by day, from the series a surface already drew by hour. */
276
+ export declare const arrivalDaysOf: (series: ArrivalSeries, options?: RhythmOptions) => DaySeries;
277
+ /** What readers did, by day, in the kind the series is of. */
278
+ export declare const actedDaysOf: (series: ActedSeries, options?: RhythmOptions) => DaySeries;
279
+ /** When readers arrive, over every day the range could speak for. */
280
+ export declare const arrivalDayShapeOf: (series: ArrivalSeries, options?: RhythmOptions) => DayShape;
281
+ /** When readers do a thing, over every day the range could speak for. */
282
+ export declare const actedDayShapeOf: (series: ActedSeries, options?: RhythmOptions) => DayShape;
283
+ /**
284
+ * The hours of the day with the most, busiest first.
285
+ *
286
+ * Only hours a day could speak for are eligible, so a list of three from a
287
+ * range holding two finished hours is two long rather than three with a
288
+ * fabricated one.
289
+ */
290
+ export declare const busiestHoursIn: (shape: DayShape, most?: number) => readonly DayHour[];
291
+ /**
292
+ * The hours of the day with the least, quietest first.
293
+ *
294
+ * *When can a change go out without anybody reading the page as it moves* — so
295
+ * the eligibility rule is the one that matters here rather than a detail:
296
+ * **an hour nothing was ever observed in is not quiet**, and naming one would
297
+ * recommend a deploy window off the absence of evidence rather than off
298
+ * evidence of absence. An observed nought is a real answer and is named.
299
+ */
300
+ export declare const quietestHoursIn: (shape: DayShape, fewest?: number) => readonly DayHour[];
301
+ export {};
302
+ //# sourceMappingURL=rhythm.d.ts.map
@@ -0,0 +1,262 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { ARRIVAL_HOUR_MS } from "./arrivals.js";
3
+ /**
4
+ * **The two ways a month of hours can be drawn, and the one of them that is a
5
+ * question nothing else here asks.**
6
+ *
7
+ * Page views are counted under the hour they began in
8
+ * ([0356](../../decisions/0356-page-views-are-counted-under-the-hour-they-began-in-as-a-sixth-counter-written-at-the-door.md))
9
+ * and what readers did under the hour they did it in
10
+ * ([0362](../../decisions/0362-what-readers-did-is-counted-under-the-hour-they-did-it-in-as-a-seventh-counter-the-fold-writes-for-the-three-delegated-kinds.md)).
11
+ * Both are read over a range as a dense hourly series, and
12
+ * [`arrivals.ts`](arrivals.ts)' `hourlySeriesOf` spells the honesty rule those
13
+ * two share: an hour with no row is a nought that is drawn, an hour before
14
+ * counting began is not drawn at all, and the hour in progress is marked rather
15
+ * than drawn as a fall.
16
+ *
17
+ * ## An hour is the unit the counter holds and not the unit a screen can draw
18
+ *
19
+ * `portal-wireframes.md` *1 · Signals* offers a range picker of **last 24
20
+ * hours, 7 days, 30 days** over a bar chart of page views. The first is 24
21
+ * bars. The third is **720**, and a screen handed 720 bars either draws them a
22
+ * third of a pixel wide or buckets them itself — and a surface bucketing them
23
+ * itself is the rule above spelled a third time, in a route group, by whoever
24
+ * is drawing the chart that week.
25
+ *
26
+ * So the fold belongs here, where the counters are read: {@link daySeriesOf}
27
+ * gives the same range as **30 bars**, and a day that the range or the clock
28
+ * cut short is marked rather than drawn as a quiet Sunday.
29
+ *
30
+ * ## The other fold answers a question no counter here has been asked
31
+ *
32
+ * A run of hours answers *how many readers arrived, and when* once. Folded the
33
+ * other way — every 09:00 of a range summed together — it answers **what a
34
+ * reader's day looks like on this deployment**: when they come, and when nobody
35
+ * does. {@link dayShapeOf} is 24 bars whatever the range, and it is the figure
36
+ * behind two questions an operator actually has: *when are my readers here*,
37
+ * and *when can I publish a change without anybody reading the page as it
38
+ * moves*.
39
+ *
40
+ * Nothing new is collected, stored or sent for either of them. Both are pure
41
+ * functions of a series a caller already holds, and the browser is not involved
42
+ * at any payload: the hour was derived at the door from the instant the request
43
+ * arrived, which is the one clock in this subsystem a page cannot move
44
+ * ([0355](../../decisions/0355-the-events-a-screen-lists-are-one-row-per-signal-and-one-page-view-is-read-on-a-key-the-caller-already-holds.md)).
45
+ *
46
+ * ## Why the shape cannot be drawn from the counts
47
+ *
48
+ * A range is hour-aligned and almost never a whole number of days, so **the
49
+ * hours of the day do not rest on the same number of days**. *Last 7 days* read
50
+ * at 09:30 holds eight 09:00s and seven 03:00s, so a shape drawn from the sums
51
+ * says readers come at 09:00 — one eighth of which is that there is one more
52
+ * 09:00 in the range. It is the plausible-false figure again: right shape,
53
+ * moves with the traffic, and wrong by a day's worth of one bar.
54
+ *
55
+ * So {@link DayHour} publishes `days` beside `count`, and the comparable figure
56
+ * is {@link DayHour.perDay} — the mean over the days that could speak for that
57
+ * hour. {@link DayShape.even} says whether the raw counts may be compared
58
+ * directly, which they may only when the range is a whole number of days.
59
+ *
60
+ * ## An hour no day could speak for is withheld and never nought
61
+ *
62
+ * *Nobody reads this page at 03:00* and *this range holds no finished 03:00* are
63
+ * one bar apart on a chart and opposite answers. The first is a measurement; the
64
+ * second is a range too short, or a deployment that began counting this morning.
65
+ * `perDay` is **absent** for the second, where every other reading in this
66
+ * subsystem withholds rather than zeroes (0301, 0326), and
67
+ * {@link quietestHoursIn} will not name an hour nothing was observed in — which
68
+ * is the one way this reading could recommend a deploy window off no evidence.
69
+ *
70
+ * ## Only whole hours reach the shape, and the arithmetic says so
71
+ *
72
+ * The hour in progress holds part of an hour's traffic, so averaging it into its
73
+ * hour of the day understates that hour by however much of it is left. It is
74
+ * left out of both the numerator and the day count, and what it held is
75
+ * published as {@link DayShape.incomplete} rather than dropped — so
76
+ * `count + incomplete` is the figure the range's own series publishes, and a
77
+ * screen that wants to say so can.
78
+ *
79
+ * The day series does the opposite with the same honesty: a partial day **keeps
80
+ * its count**, because what happened in it happened, and carries
81
+ * {@link DayBucket.hours} and {@link DayBucket.whole} so a bar nobody has
82
+ * finished arriving in is not drawn like the twenty-nine before it. The sum over
83
+ * the days is the sum over the hours, always, which is asserted rather than
84
+ * argued.
85
+ *
86
+ * ## Counts add and days do not
87
+ *
88
+ * Both folds take occurrences by addition and denominators by distinctness,
89
+ * which is the rule the hourly counters were built under: *occurrences add,
90
+ * distinctness does not* (0362). An hour handed over twice adds its count twice
91
+ * and is one hour of one day either way — the fault worth guarding, because
92
+ * counting the same thing twice in a denominator is permanent
93
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
94
+ *
95
+ * The input is a **series** and not a store's rows, and the type is what says
96
+ * so: a row of either hourly table names a tree, a revision and an audience, so
97
+ * three of them can name one hour, and only a series has been through the fold
98
+ * that makes an hour unique. `whole` is the field no row carries and every
99
+ * series does, so the mistake does not typecheck.
100
+ *
101
+ * ## The offset is a fixed number of hours and is not a time zone
102
+ *
103
+ * Both counters bucket by UTC hour, so a deployment whose readers are all in one
104
+ * country has its whole day shifted — a nine-o'clock peak in California arrives
105
+ * here as a 17:00 bar. {@link RhythmOptions.offsetHours} shifts where the day is
106
+ * cut and what each hour of the day is called, and it is **whole hours, applied
107
+ * flatly**: an hour bucket cannot be divided, so a zone at a half-hour offset is
108
+ * not nameable from these counters at all, and a zone that observes summer time
109
+ * is named by one offset or the other and is an hour out for the rest of the
110
+ * range. A screen drawing a local day says which offset it drew, which is why
111
+ * both readings publish it back.
112
+ */
113
+ /** A day, in the unit the counters are kept in. The prefix is `ARRIVAL_HOUR_MS`'. */
114
+ export const ARRIVAL_DAY_MS = 86_400_000;
115
+ /** How many hours a day of these counters has, which is what a shape has bars. */
116
+ export const HOURS_IN_DAY = 24;
117
+ /**
118
+ * The members, published so that the set can be enumerated rather than
119
+ * remembered.
120
+ *
121
+ * Every other silence set in this subsystem publishes one, and the census over
122
+ * them ([`silences.ts`](silences.ts)) is built by mapping each set's members
123
+ * through its own `meaningOf` — so a set with no published members is a set a
124
+ * census can only reach by hand, which is how this one stayed outside it for
125
+ * three days. `silence-sweep.test.ts` now fails on a set that publishes none.
126
+ */
127
+ export const DAY_SHAPE_SILENCES = everyMemberOf()([
128
+ "unmeasured",
129
+ "unsettled",
130
+ ]);
131
+ /**
132
+ * One line per silence, for a surface saying why a day has no shape.
133
+ *
134
+ * **The only one of the four written for 0407 that is new text**, because this
135
+ * reading publishes no standing for the sentence to have already been in. Both
136
+ * members resolve themselves and the sentences say how, since the two remedies
137
+ * are a week apart: one wants readers, the other wants the hour to end.
138
+ */
139
+ export const describeDayShapeSilence = (silence) => {
140
+ switch (silence) {
141
+ case "unmeasured":
142
+ return "nothing has ever been counted in this scope, so the series this folds is empty";
143
+ case "unsettled":
144
+ return "the range holds hours and not one of them is over, so there is no whole hour to fold";
145
+ }
146
+ };
147
+ const shiftOf = (options) => (Math.trunc(options.offsetHours ?? 0) % HOURS_IN_DAY) * ARRIVAL_HOUR_MS;
148
+ const dayAt = (hour, shift) => Math.floor((hour + shift) / ARRIVAL_DAY_MS) * ARRIVAL_DAY_MS - shift;
149
+ const hourOfDayAt = (hour, shift) => Math.floor(((((hour + shift) / ARRIVAL_HOUR_MS) % HOURS_IN_DAY) + HOURS_IN_DAY) % HOURS_IN_DAY);
150
+ /**
151
+ * An hourly series folded into its days.
152
+ *
153
+ * Generic over the hour because the two hourly readings spell their number
154
+ * differently — `views` on an arrival hour, `count` on an acted one — and
155
+ * {@link arrivalDaysOf} and {@link actedDaysOf} are the two callers that
156
+ * exist, so no surface writes the accessor.
157
+ */
158
+ export const daySeriesOf = (series, count, options = {}) => {
159
+ const shift = shiftOf(options);
160
+ const counted = new Map();
161
+ const hours = new Map();
162
+ const unfinished = new Set();
163
+ for (const hour of series.hours) {
164
+ const day = dayAt(hour.hour, shift);
165
+ counted.set(day, (counted.get(day) ?? 0) + count(hour));
166
+ (hours.get(day) ?? hours.set(day, new Set()).get(day)).add(hour.hour);
167
+ if (!hour.whole)
168
+ unfinished.add(day);
169
+ }
170
+ const days = [...counted.keys()]
171
+ .sort((one, other) => one - other)
172
+ .map((day) => {
173
+ const present = hours.get(day)?.size ?? 0;
174
+ return {
175
+ day,
176
+ count: counted.get(day) ?? 0,
177
+ hours: present,
178
+ whole: present === HOURS_IN_DAY && !unfinished.has(day),
179
+ };
180
+ });
181
+ return {
182
+ range: series.range,
183
+ days,
184
+ count: days.reduce((sum, day) => sum + day.count, 0),
185
+ offsetHours: shift / ARRIVAL_HOUR_MS,
186
+ clipped: series.clipped,
187
+ partial: days.filter((day) => !day.whole).length,
188
+ };
189
+ };
190
+ /**
191
+ * The hours of the day a series' whole hours fell in.
192
+ *
193
+ * Generic for {@link daySeriesOf}'s reason, with {@link arrivalDayShapeOf} and
194
+ * {@link actedDayShapeOf} as the two callers that exist.
195
+ */
196
+ export const dayShapeOf = (series, count, options = {}) => {
197
+ const shift = shiftOf(options);
198
+ const counted = new Map();
199
+ const days = new Map();
200
+ const observed = new Set();
201
+ let incomplete = 0;
202
+ for (const hour of series.hours) {
203
+ if (!hour.whole) {
204
+ incomplete += count(hour);
205
+ continue;
206
+ }
207
+ const of = hourOfDayAt(hour.hour, shift);
208
+ const day = dayAt(hour.hour, shift);
209
+ counted.set(of, (counted.get(of) ?? 0) + count(hour));
210
+ (days.get(of) ?? days.set(of, new Set()).get(of)).add(day);
211
+ observed.add(day);
212
+ }
213
+ const hours = Array.from({ length: HOURS_IN_DAY }, (_, of) => {
214
+ const over = days.get(of)?.size ?? 0;
215
+ const total = counted.get(of) ?? 0;
216
+ return {
217
+ hour: of,
218
+ days: over,
219
+ count: total,
220
+ ...(over === 0 ? {} : { perDay: total / over }),
221
+ };
222
+ });
223
+ const silence = observed.size > 0 ? undefined : series.hours.length === 0 ? "unmeasured" : "unsettled";
224
+ return {
225
+ hours,
226
+ count: hours.reduce((sum, hour) => sum + hour.count, 0),
227
+ incomplete,
228
+ days: observed.size,
229
+ even: hours.every((hour) => hour.days === hours[0].days),
230
+ offsetHours: shift / ARRIVAL_HOUR_MS,
231
+ ...(silence === undefined ? {} : { silence }),
232
+ };
233
+ };
234
+ /** Page views by day, from the series a surface already drew by hour. */
235
+ export const arrivalDaysOf = (series, options = {}) => daySeriesOf(series, (hour) => hour.views, options);
236
+ /** What readers did, by day, in the kind the series is of. */
237
+ export const actedDaysOf = (series, options = {}) => daySeriesOf(series, (hour) => hour.count, options);
238
+ /** When readers arrive, over every day the range could speak for. */
239
+ export const arrivalDayShapeOf = (series, options = {}) => dayShapeOf(series, (hour) => hour.views, options);
240
+ /** When readers do a thing, over every day the range could speak for. */
241
+ export const actedDayShapeOf = (series, options = {}) => dayShapeOf(series, (hour) => hour.count, options);
242
+ const ranked = (shape, by) => shape.hours.filter((hour) => hour.perDay !== undefined).sort(by);
243
+ const take = (hours, many) => hours.slice(0, Math.max(0, Math.trunc(many)));
244
+ /**
245
+ * The hours of the day with the most, busiest first.
246
+ *
247
+ * Only hours a day could speak for are eligible, so a list of three from a
248
+ * range holding two finished hours is two long rather than three with a
249
+ * fabricated one.
250
+ */
251
+ export const busiestHoursIn = (shape, most = 3) => take(ranked(shape, (one, other) => other.perDay - one.perDay || one.hour - other.hour), most);
252
+ /**
253
+ * The hours of the day with the least, quietest first.
254
+ *
255
+ * *When can a change go out without anybody reading the page as it moves* — so
256
+ * the eligibility rule is the one that matters here rather than a detail:
257
+ * **an hour nothing was ever observed in is not quiet**, and naming one would
258
+ * recommend a deploy window off the absence of evidence rather than off
259
+ * evidence of absence. An observed nought is a real answer and is named.
260
+ */
261
+ export const quietestHoursIn = (shape, fewest = 3) => take(ranked(shape, (one, other) => one.perDay - other.perDay || one.hour - other.hour), fewest);
262
+ //# sourceMappingURL=rhythm.js.map