@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,180 @@
1
+ /**
2
+ * The sixth contract suite both reader-signal tally stores are run against:
3
+ * **page views are counted under the hour they began in, and the hours of a
4
+ * revision sum to its total** (`arrivals.ts`).
5
+ *
6
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `applied-window.contract.ts` and `kept.contract.ts` are: that
8
+ * directory is another lane's and this is reader-signal work. The finding filed
9
+ * with 0316 asks for the set to be moved together, which is one import away.
10
+ *
11
+ * **Every property here needs two implementations to be worth asserting.** The
12
+ * hour is a `timestamptz` in one store and a number in the other, so a bucket
13
+ * is a `Date` that has to come back as the instant it went in as; the pair of
14
+ * writes is a transaction in one and two map writes in the other; and two
15
+ * counts of one hour in a single call are an `ON CONFLICT` Postgres **raises**
16
+ * on and a `Map` silently overwrites. Each of those is a way for a chart to
17
+ * stop summing to the counter it is drawn beside, which is permanent (0158).
18
+ */
19
+ import { describe, expect, it } from "vitest";
20
+ import { OTHER_TREE, RIDERS, SKIERS, TREE } from "../testing/reader-signal-contract.js";
21
+ import { ARRIVAL_HOUR_MS } from "./arrivals.js";
22
+ const HOUR = ARRIVAL_HOUR_MS;
23
+ const MIDNIGHT = Date.parse("2026-11-06T00:00:00.000Z");
24
+ const at = (hour, minutes = 0) => new Date(MIDNIGHT + hour * HOUR + minutes * 60_000).toISOString();
25
+ const opening = (views, overrides = {}) => ({
26
+ treeId: TREE,
27
+ revision: 1,
28
+ views,
29
+ ...overrides,
30
+ });
31
+ const unwrap = (result) => {
32
+ if (!result.ok)
33
+ throw new Error(result.error.detail);
34
+ return result.value;
35
+ };
36
+ export const describeArrivalHourContract = (name, make) => {
37
+ describe(`${name} — page views by the hour they began in`, () => {
38
+ const counted = async () => {
39
+ const store = await make();
40
+ unwrap(await store.opened([opening(2)], at(9, 15), SKIERS));
41
+ return store;
42
+ };
43
+ it("files an arrival under the hour of the instant it was counted at", async () => {
44
+ const store = await counted();
45
+ const { hours } = unwrap(await store.arrivals());
46
+ expect(hours).toEqual([
47
+ {
48
+ audienceId: SKIERS,
49
+ treeId: TREE,
50
+ revision: 1,
51
+ hour: MIDNIGHT + 9 * HOUR,
52
+ views: 2,
53
+ updatedAt: at(9, 15),
54
+ },
55
+ ]);
56
+ });
57
+ it("adds a second delivery in the same hour to the same row", async () => {
58
+ const store = await counted();
59
+ unwrap(await store.opened([opening(3)], at(9, 59), SKIERS));
60
+ const { hours } = unwrap(await store.arrivals());
61
+ expect(hours).toHaveLength(1);
62
+ expect(hours[0]?.views).toBe(5);
63
+ });
64
+ it("puts a delivery one minute later in the next hour", async () => {
65
+ const store = await counted();
66
+ unwrap(await store.opened([opening(3)], at(10, 0), SKIERS));
67
+ const { hours } = unwrap(await store.arrivals());
68
+ expect(hours.map((row) => [row.hour, row.views])).toEqual(expect.arrayContaining([
69
+ [MIDNIGHT + 9 * HOUR, 2],
70
+ [MIDNIGHT + 10 * HOUR, 3],
71
+ ]));
72
+ });
73
+ /**
74
+ * Two entries naming one hour inside a single call are added, which is the
75
+ * guarantee `counters.ts` gives in front of the driver: Postgres refuses to
76
+ * affect one row twice in one command and a `Map` would keep the last.
77
+ */
78
+ it("adds two openings of one revision handed over together", async () => {
79
+ const store = await make();
80
+ unwrap(await store.opened([opening(2), opening(3)], at(9), SKIERS));
81
+ const { hours } = unwrap(await store.arrivals());
82
+ expect(hours).toHaveLength(1);
83
+ expect(hours[0]?.views).toBe(5);
84
+ });
85
+ it("keeps an hour of two audiences apart (0284)", async () => {
86
+ const store = await counted();
87
+ unwrap(await store.opened([opening(4)], at(9, 30), RIDERS));
88
+ const { hours } = unwrap(await store.arrivals());
89
+ expect(hours).toHaveLength(2);
90
+ expect(unwrap(await store.arrivals({ audience: RIDERS })).hours[0]?.views).toBe(4);
91
+ });
92
+ it("keeps an hour of two trees apart", async () => {
93
+ const store = await counted();
94
+ unwrap(await store.opened([opening(4, { treeId: OTHER_TREE })], at(9, 30), SKIERS));
95
+ expect(unwrap(await store.arrivals()).hours).toHaveLength(2);
96
+ expect(unwrap(await store.arrivals({ treeId: TREE })).hours).toHaveLength(1);
97
+ });
98
+ it("keeps an hour of two revisions apart", async () => {
99
+ const store = await counted();
100
+ unwrap(await store.opened([opening(4, { revision: 2 })], at(9, 30), SKIERS));
101
+ expect(unwrap(await store.arrivals()).hours).toHaveLength(2);
102
+ expect(unwrap(await store.arrivals({ revision: 2 })).hours[0]?.views).toBe(4);
103
+ });
104
+ /**
105
+ * The invariant the pair of writes exists for: every arrival is in both
106
+ * counters, so a chart drawn off the hours sums to the total drawn beside
107
+ * it.
108
+ */
109
+ it("counts every arrival into the revision's total as well", async () => {
110
+ const store = await counted();
111
+ unwrap(await store.opened([opening(3)], at(13, 5), SKIERS));
112
+ const { hours } = unwrap(await store.arrivals());
113
+ const [total] = unwrap(await store.pageViews());
114
+ expect(hours.reduce((sum, row) => sum + row.views, 0)).toBe(total?.opened);
115
+ expect(total?.opened).toBe(5);
116
+ });
117
+ it("counts nothing at all where the instant is not one", async () => {
118
+ const store = await make();
119
+ const written = await store.opened([opening(2)], "whenever", SKIERS);
120
+ expect(written.ok).toBe(false);
121
+ expect(unwrap(await store.arrivals()).hours).toEqual([]);
122
+ expect(unwrap(await store.pageViews())).toEqual([]);
123
+ });
124
+ it("writes nothing for a delivery that opened nothing", async () => {
125
+ const store = await make();
126
+ unwrap(await store.opened([], at(9), SKIERS));
127
+ expect(unwrap(await store.arrivals()).hours).toEqual([]);
128
+ });
129
+ describe("over a range", () => {
130
+ const spread = async () => {
131
+ const store = await make();
132
+ for (const hour of [1, 5, 9]) {
133
+ unwrap(await store.opened([opening(hour)], at(hour), SKIERS));
134
+ }
135
+ return store;
136
+ };
137
+ it("holds the hours from the start of the range to the end, and not the ends' neighbours", async () => {
138
+ const store = await spread();
139
+ const { hours } = unwrap(await store.arrivals({ from: MIDNIGHT + 5 * HOUR, to: MIDNIGHT + 9 * HOUR }));
140
+ expect(hours.map((row) => row.views)).toEqual([5]);
141
+ });
142
+ it("is unbounded on a side the request leaves out", async () => {
143
+ const store = await spread();
144
+ expect(unwrap(await store.arrivals({ to: MIDNIGHT + 9 * HOUR })).hours).toHaveLength(2);
145
+ expect(unwrap(await store.arrivals({ from: MIDNIGHT + 5 * HOUR })).hours).toHaveLength(2);
146
+ });
147
+ it("answers an empty range with no hours and the beginning still named", async () => {
148
+ const store = await spread();
149
+ const read = unwrap(await store.arrivals({ from: MIDNIGHT + 20 * HOUR, to: MIDNIGHT + 21 * HOUR }));
150
+ expect(read.hours).toEqual([]);
151
+ expect(read.begins).toBe(MIDNIGHT + HOUR);
152
+ });
153
+ });
154
+ describe("the hour counting began", () => {
155
+ it("is the earliest hour the scope has, whatever range was asked for", async () => {
156
+ const store = await make();
157
+ unwrap(await store.opened([opening(1)], at(9), SKIERS));
158
+ unwrap(await store.opened([opening(1)], at(2), SKIERS));
159
+ const read = unwrap(await store.arrivals({ from: MIDNIGHT + 9 * HOUR, to: MIDNIGHT + 10 * HOUR }));
160
+ expect(read.begins).toBe(MIDNIGHT + 2 * HOUR);
161
+ });
162
+ it("is absent where nothing has ever been counted", async () => {
163
+ const store = await make();
164
+ expect(unwrap(await store.arrivals()).begins).toBeUndefined();
165
+ });
166
+ it("narrows with the request, so a page says when it began rather than when the deployment did", async () => {
167
+ const store = await make();
168
+ unwrap(await store.opened([opening(1)], at(2), SKIERS));
169
+ unwrap(await store.opened([opening(1, { treeId: OTHER_TREE })], at(9), SKIERS));
170
+ expect(unwrap(await store.arrivals({ treeId: OTHER_TREE })).begins).toBe(MIDNIGHT + 9 * HOUR);
171
+ });
172
+ });
173
+ it("is not changed by being read", async () => {
174
+ const store = await counted();
175
+ expect(unwrap(await store.arrivals()).hours[0]?.views).toBe(2);
176
+ expect(unwrap(await store.arrivals()).hours[0]?.views).toBe(2);
177
+ });
178
+ });
179
+ };
180
+ //# sourceMappingURL=arrivals.contract.js.map
@@ -0,0 +1,375 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { TreeId } from "../ids.js";
3
+ import { type Result } from "../result.js";
4
+ import type { ReaderSignalStoreError } from "./journal.js";
5
+ import type { RevisionViews } from "./page-views.js";
6
+ import { type Ratio } from "./ratios.js";
7
+ /**
8
+ * **When** readers arrived, which is the one thing every counter in this
9
+ * subsystem had thrown away.
10
+ *
11
+ * `page-views.ts` counts the page views that *began* on a revision — exact,
12
+ * counted once, at the door, from the marker a delivery carries
13
+ * ([0214](../../decisions/0214-where-readers-are-is-a-floored-bucket-counted-at-the-door-and-a-page-view-says-when-it-began.md)).
14
+ * It is one number per revision for all time, so it can answer *how many
15
+ * readers* and can never answer *how many yesterday*. Nothing else could
16
+ * either: a tally keeps no time (rule 5 of `docs/signals.md`), and the only
17
+ * rows with an instant on them are the kept deliveries, which are paged by
18
+ * delivery and bounded by the window a deployment keeps them for (0351). A
19
+ * thirty-day chart read from those is thirty days of rows on every render, and
20
+ * a bar drawn from a capped scan is a **wrong number** rather than a shorter
21
+ * list — which is why `Loom portal` filed for this rather than drawing one.
22
+ *
23
+ * So this is the third thing derived from the same marker, after the opening
24
+ * count and the region bucket: **the same arrivals, filed under the hour they
25
+ * arrived in.** Nothing is sent for it, nothing is stored about anybody, and
26
+ * the browser is not involved — the hour is the instant the door was already
27
+ * stamping every counter this delivery moves.
28
+ *
29
+ * ## Why it is a counter and not a read of the kept deliveries
30
+ *
31
+ * The deliveries could answer it, twice over, and both routes are worse.
32
+ *
33
+ * - **Grouping the kept rows by `view` key** and taking each key's earliest
34
+ * receipt is a scan of the whole kept window, and it is a query *about view
35
+ * keys* — the one value in this seam that exists so a funnel can be
36
+ * correlated inside one page view and for nothing else (0146). A counter that
37
+ * needs no key at all is strictly the safer of the two.
38
+ * - **Counting deliveries per hour** needs neither, and counts a reader who
39
+ * stayed ten minutes as a hundred readers. 0214 refused that shape for the
40
+ * region map and it is refused here for the same reason.
41
+ *
42
+ * And a counter answers for as long as the counters live, where either read
43
+ * answers only for the kept window. **The hour outlives the row it could have
44
+ * been derived from**, which is the one consequence of this worth saying out
45
+ * loud rather than leaving to be noticed: a deployment that keeps deliveries
46
+ * for thirty days can still say how many readers arrived in an hour last year.
47
+ * It names no reader, no place and no page view — it is a count of page views
48
+ * of one revision, which is the figure `page-views.ts` already calls *nowhere
49
+ * and nobody* — but it is a count against a clock, and that is new.
50
+ *
51
+ * ## The hour is the unit
52
+ *
53
+ * Finer is not available and coarser would not serve the screen that asked.
54
+ * A *last 24 hours* chart needs twenty-four bars, so a day bucket cannot draw
55
+ * it; a minute bucket is sixty times the rows for a resolution no reading has
56
+ * ever asked for. A surface wanting days sums hours, which is addition over
57
+ * counts that were each counted once.
58
+ *
59
+ * **The hour is UTC and the bucket is its start instant.** A deployment that
60
+ * draws local time shifts the labels, which is a decision about a reader's
61
+ * screen rather than about a counter; storing an offset would make the same row
62
+ * mean two things in two places.
63
+ *
64
+ * Pure: no store, no clock, no DOM, and no import that reaches a package.
65
+ */
66
+ /** One hour, in milliseconds, which is the bucket every row here is filed in. */
67
+ export declare const ARRIVAL_HOUR_MS = 3600000;
68
+ /**
69
+ * The hour an instant falls in, as the instant that hour began.
70
+ *
71
+ * `undefined` where the argument is not an instant. It is the caller's clock
72
+ * and so should never be, but the alternative to saying so is a bucket of
73
+ * `NaN` in a counter — and a counter row nothing can read is worse than a
74
+ * write that refused.
75
+ */
76
+ export declare const arrivalHourOf: (instant: string) => number | undefined;
77
+ /** Page views that began in one hour, of one revision of one tree. */
78
+ export type ArrivalHourCount = {
79
+ readonly treeId: TreeId;
80
+ readonly revision: number;
81
+ /** The hour they arrived in, as the instant it began (UTC). */
82
+ readonly hour: number;
83
+ /** Page views that *began* in this hour, so a longer visit is not a bigger number. */
84
+ readonly views: number;
85
+ };
86
+ /**
87
+ * An hour's count as the store keeps it. See `StoredTally.audienceId` (0284).
88
+ */
89
+ export type StoredArrivalHour = ArrivalHourCount & {
90
+ readonly audienceId: AudienceId;
91
+ readonly updatedAt: string;
92
+ };
93
+ /**
94
+ * What one delivery adds, which is its openings filed under the hour the door
95
+ * read them in.
96
+ *
97
+ * **It is handed the openings rather than the delivery**, exactly as
98
+ * `regionCountsOf` is and for the same reason: the walk that finds them, and
99
+ * the deduplication that makes a retried opening inside one delivery a single
100
+ * arrival, is `openingsOf` in `page-views.ts`. Three counters derived from one
101
+ * walk cannot disagree about how many readers arrived; three walks would, and
102
+ * the disagreement would surface as an hourly chart whose bars do not sum to
103
+ * the number of page views there were.
104
+ *
105
+ * **The instant is the one every other counter on this delivery is stamped
106
+ * with**, so an hour is never a second opinion about when the delivery was
107
+ * received. A failure rather than an empty list where that instant will not
108
+ * parse: openings written to one counter and not the other would make the two
109
+ * numbers differ for a reason no reading could name.
110
+ */
111
+ export declare const arrivalHoursOf: (openings: readonly RevisionViews[], at: string) => Result<readonly ArrivalHourCount[], ReaderSignalStoreError>;
112
+ /**
113
+ * What a ranged read of the counter hands back.
114
+ *
115
+ * The rows in the range **and** the first hour the scope has any row for, which
116
+ * is two statements and one call. A caller needs both to draw anything honest —
117
+ * a range of thirty days on a deployment that began counting a week ago is
118
+ * seven bars and a sentence, not seven bars and twenty-three empty ones — and a
119
+ * caller that had to ask twice would be the caller that asks once.
120
+ */
121
+ export type StoredArrivals = {
122
+ /** Every hour in the range that has a row, in no particular order. */
123
+ readonly hours: readonly StoredArrivalHour[];
124
+ /**
125
+ * The first hour this scope has ever counted an arrival in, whatever range
126
+ * was asked for.
127
+ *
128
+ * Absent means *nothing has ever been counted here*, which is a different
129
+ * sentence from *nobody arrived in the range you asked about* — the
130
+ * distinction this subsystem keeps everywhere a reading can be empty for two
131
+ * reasons (0309, 0347).
132
+ *
133
+ * It narrows with the request's tree, revision and audience, so *By page* can
134
+ * say when counting began for that page rather than for the deployment.
135
+ */
136
+ readonly begins?: number;
137
+ };
138
+ /**
139
+ * A stretch of time, in milliseconds, closed at the start and open at the end.
140
+ *
141
+ * **An hour belongs to the range that its own start falls in**, which is the
142
+ * one rule here a caller has to hold: a range is a set of buckets rather than a
143
+ * set of instants, so a range running from half past ten holds the eleven
144
+ * o'clock bucket and not the ten o'clock one. {@link arrivalRangeOf} builds
145
+ * ranges that are whole hours, which is what makes the rule invisible — and
146
+ * what makes {@link arrivalRangeBefore} give a period with exactly as many buckets in
147
+ * it.
148
+ */
149
+ export type ArrivalRange = {
150
+ readonly from: number;
151
+ readonly to: number;
152
+ };
153
+ /** One hour of a range, which is one bar. */
154
+ export type ArrivalHour = {
155
+ /** The instant the hour began (UTC). */
156
+ readonly hour: number;
157
+ readonly views: number;
158
+ /**
159
+ * Whether this hour is over and inside the range.
160
+ *
161
+ * The last bar is the one this is for: *the last 24 hours* ends in an hour
162
+ * nobody has finished arriving in, and a screen that drew it like the other
163
+ * twenty-three would show every reader a dip at the right-hand edge that is
164
+ * the clock rather than the traffic. False also where the range itself cuts
165
+ * the hour short, which is what an unaligned range does to its last bucket.
166
+ */
167
+ readonly whole: boolean;
168
+ };
169
+ /**
170
+ * The whole hours ending with the hour an instant falls in.
171
+ *
172
+ * `arrivalRangeOf(now, 24)` is *the last 24 hours*: twenty-three hours that are
173
+ * over and the one in progress. Hour-aligned on both ends, which is what the
174
+ * comparison needs — {@link arrivalRangeBefore} of an aligned range is aligned, so the
175
+ * two periods a change is taken over hold the same number of buckets, and a
176
+ * percentage of two honest counts stays honest.
177
+ */
178
+ export declare const arrivalRangeOf: (now: number, hours: number) => ArrivalRange;
179
+ /**
180
+ * Page views by hour over a range, dense, with the hours this deployment
181
+ * cannot speak for left out rather than drawn as nought.
182
+ */
183
+ export type ArrivalSeries = {
184
+ /** The range this is a series over, as asked for. */
185
+ readonly range: ArrivalRange;
186
+ /**
187
+ * One entry per hour, ascending, from the later of the range's first hour and
188
+ * the hour counting began.
189
+ *
190
+ * Dense: an hour nobody arrived in is `views: 0` and is present, because a
191
+ * chart that omits a quiet hour draws a narrower week. Empty where counting
192
+ * began after the range ended, or where nothing has ever been counted.
193
+ */
194
+ readonly hours: readonly ArrivalHour[];
195
+ /** Page views that began inside the range, which is the sum of the hours above. */
196
+ readonly views: number;
197
+ /**
198
+ * The first hour the scope has ever counted, carried through from the store.
199
+ *
200
+ * A surface says *counting began on the 23rd* with it. Absent means nothing
201
+ * has ever been counted, and the series is then empty for a reason that is
202
+ * not *nobody came*.
203
+ */
204
+ readonly begins?: number;
205
+ /**
206
+ * Whether the range starts before counting did.
207
+ *
208
+ * The reason the series can be shorter than the range asked for, published
209
+ * rather than left to a caller comparing two instants — because the
210
+ * comparison has an edge (counting may have begun inside the range's first
211
+ * hour) and a surface getting it wrong would claim a quiet week.
212
+ */
213
+ readonly clipped: boolean;
214
+ };
215
+ /** What a series may be told besides the rows, which is the one thing a clock knows. */
216
+ export type ArrivalSeriesOptions = {
217
+ /**
218
+ * Now, where a caller has it, so the hour in progress is marked as one.
219
+ *
220
+ * Omitted is a series about a stretch that is over, where every bucket the
221
+ * range covers whole is whole. Handed in rather than read from a clock here
222
+ * for the reason every other instant in this subsystem is: a reading is a
223
+ * pure function of what it was given, so two figures on one screen cannot
224
+ * disagree about when it was taken.
225
+ */
226
+ readonly now?: number;
227
+ };
228
+ /**
229
+ * The hours of a range, as the counter answers for them.
230
+ *
231
+ * Rows are summed into their hour, which is what makes this readable over a
232
+ * scope holding several trees, revisions or audiences: **arrivals add**, because
233
+ * a reader who arrived arrived once whichever form of whichever page they were
234
+ * served (0297, 0299). A caller wanting them apart asks for one tree.
235
+ *
236
+ * Rows outside the range are ignored rather than refused. A store answers the
237
+ * range it was asked for, and a reading that threw on a row it did not expect
238
+ * would be a reading that cannot be given a wider read to narrow — which is
239
+ * exactly what {@link arrivalChangeOf} does with it.
240
+ */
241
+ export declare const arrivalSeriesOf: (stored: StoredArrivals, range: ArrivalRange, options?: ArrivalSeriesOptions) => ArrivalSeries;
242
+ /** One bucket of a dense hourly series, before a reading names what it counted. */
243
+ export type HourlyBucket = {
244
+ readonly hour: number;
245
+ readonly count: number;
246
+ readonly whole: boolean;
247
+ };
248
+ /** A dense series and what it adds up to, which is what a reading dresses. */
249
+ export type HourlyFill = {
250
+ readonly hours: readonly HourlyBucket[];
251
+ readonly total: number;
252
+ readonly clipped: boolean;
253
+ };
254
+ /**
255
+ * The rule every hourly series in this subsystem follows, spelled once.
256
+ *
257
+ * Three readings now draw bars over a range — page views by hour (0356), and
258
+ * what readers did by hour (`acted.ts`), in a series and in a comparison — and
259
+ * the rule they share is not the arithmetic but the **honesty**: an hour with
260
+ * no row is a nought that is drawn, an hour before counting began is not drawn
261
+ * at all, and the hour in progress is marked rather than drawn as a fall. Three
262
+ * spellings of that would be three chances for one chart to claim a quiet week
263
+ * the deployment never had.
264
+ *
265
+ * It is exported rather than private because `acted.ts` is a module and not a
266
+ * function in this one. A reading hands over its rows, the first hour its scope
267
+ * ever counted, the range, and which number on a row it is counting.
268
+ */
269
+ export declare const hourlySeriesOf: <Row extends {
270
+ readonly hour: number;
271
+ }>(rows: readonly Row[], begins: number | undefined, range: ArrivalRange, count: (row: Row) => number, options?: ArrivalSeriesOptions) => HourlyFill;
272
+ /**
273
+ * The stretch of the same length immediately before a range.
274
+ *
275
+ * The period a *page views in the range* figure is compared against, computed
276
+ * here rather than at a call site so that the two ranges a comparison is taken
277
+ * over cannot be of different lengths — which is the one way to make a
278
+ * percentage of two honest counts dishonest.
279
+ */
280
+ export declare const arrivalRangeBefore: (range: ArrivalRange) => ArrivalRange;
281
+ /**
282
+ * Page views in a range against page views in the period before it.
283
+ *
284
+ * The figure the wireframe puts over the whole screen, and the one that is a
285
+ * lie if the earlier period is one the deployment was not counting through.
286
+ */
287
+ export type ArrivalChange = {
288
+ readonly range: ArrivalRange;
289
+ /** The equal-length period the comparison is against, which is {@link arrivalRangeBefore}. */
290
+ readonly before: ArrivalRange;
291
+ readonly views: number;
292
+ /**
293
+ * Page views in the earlier period, or `null` where counting had not begun
294
+ * when it started.
295
+ *
296
+ * `null` is not nought and the difference is the whole of this field: a
297
+ * deployment that upgraded on Tuesday has no arrivals before Tuesday and
298
+ * never had any readers missing either. Reporting nought there would publish
299
+ * *every reader you have is new this week* on every deployment's first month.
300
+ */
301
+ readonly was: number | null;
302
+ /**
303
+ * The quotient, or why there is none (`ratios.ts`).
304
+ *
305
+ * `unmeasured` where the earlier period predates counting, `from-nothing`
306
+ * where it was counted and held no arrivals — which is the rise a surface
307
+ * most wants to draw and could least afford to read as *nothing to compare*.
308
+ */
309
+ readonly ratio: Ratio;
310
+ };
311
+ /**
312
+ * Both figures and the quotient, from one read.
313
+ *
314
+ * The read has to span both periods, which is what `arrivalRangeBefore` is for: a
315
+ * caller asks the store for `{ from: arrivalRangeBefore(range).from, to: range.to }`
316
+ * and hands the result here. Taking two reads would be two scans and a seam
317
+ * where the clock moved between them.
318
+ */
319
+ export declare const arrivalChangeOf: (stored: StoredArrivals, range: ArrivalRange, options?: ArrivalSeriesOptions) => ArrivalChange;
320
+ /**
321
+ * What a surface asks for: a range, the narrowing, and the clock.
322
+ *
323
+ * The three narrowings are the counter read's own, so a chart of one page is
324
+ * this with a `treeId` on it.
325
+ */
326
+ export type ArrivalReadingRequest = {
327
+ readonly range: ArrivalRange;
328
+ /** Absent reads every tree the handle can see, which is the scope rule (0020). */
329
+ readonly treeId?: TreeId;
330
+ /** Absent reads every audience (0284), whose arrivals then add. */
331
+ readonly audience?: AudienceId | undefined;
332
+ /** Absent reads every revision, whose arrivals then add. */
333
+ readonly revision?: number;
334
+ /** Now, where the caller has it, so the hour in progress is marked as one. */
335
+ readonly now?: number;
336
+ };
337
+ /**
338
+ * The one method of the counter handle a reading of this needs.
339
+ *
340
+ * Named rather than written inline so that a reading joining two counters —
341
+ * what readers did, over the page views they did it in (`acted.ts`) — can ask
342
+ * for both halves without respelling either.
343
+ */
344
+ export type ArrivalCounterHandle = {
345
+ readonly arrivals: (request?: {
346
+ readonly treeId?: TreeId;
347
+ readonly audience?: AudienceId | undefined;
348
+ readonly revision?: number;
349
+ readonly from?: number;
350
+ readonly to?: number;
351
+ }) => Promise<Result<StoredArrivals, ReaderSignalStoreError>>;
352
+ };
353
+ /** The chart and the two figures above it, from one read. */
354
+ export type ArrivalReading = {
355
+ readonly series: ArrivalSeries;
356
+ readonly change: ArrivalChange;
357
+ };
358
+ /**
359
+ * The chart, the range's figure and the change on the period before it, in one
360
+ * call against a counter handle.
361
+ *
362
+ * **It exists because the composition has a wrong version that type-checks.**
363
+ * The change is over two periods, so the read has to span both — and a caller
364
+ * who read `{ from: range.from }`, which is the obvious line, would get a
365
+ * comparison whose earlier period is empty **because it was not read** rather
366
+ * than because nobody arrived in it. That reads as *every reader you have is
367
+ * new*, on a screen, from a store that holds the right answer. This takes the
368
+ * range a surface is drawing and derives the read from it, so there is nothing
369
+ * to get wrong.
370
+ *
371
+ * The store handle is narrowed to the one method, so a reading cannot reach a
372
+ * counter it was not asked about.
373
+ */
374
+ export declare const readReaderArrivals: (store: ArrivalCounterHandle, request: ArrivalReadingRequest) => Promise<Result<ArrivalReading, ReaderSignalStoreError>>;
375
+ //# sourceMappingURL=arrivals.d.ts.map