@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,291 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { countWords } from "./words.js";
3
+ /**
4
+ * Whether a part was read or scrolled past.
5
+ *
6
+ * [`parts.ts`](parts.ts) answers *which parts came into view*, and it has
7
+ * always been careful to say only that: `read` there means **a row says this
8
+ * part was on a reader's screen**. A band a reader scrolled through at speed is
9
+ * `read` by that definition and was not read by any other, and a page of them
10
+ * reports as a page that was read from top to bottom. That is the
11
+ * plausible-false-number failure this subsystem keeps finding in new places —
12
+ * the figure is the right shape, it is on the screen, and nobody can tell it is
13
+ * wrong.
14
+ *
15
+ * The missing half was already in the rows. A tally carries `dwellMs` beside
16
+ * `reached`, and since [0223](../../decisions/0223-a-prop-is-copy-when-a-reader-could-quote-it.md)
17
+ * the tree carries the words a part says. **Time on screen against the time its
18
+ * words take to read** is the question, and both sides of it are already held:
19
+ * nothing is added to a payload, a browser, a column, a store or the
20
+ * vocabulary. It is the fifth thing taken out of the server-side join of
21
+ * [0212](../../decisions/0212-what-a-reader-signal-means-is-joined-to-the-tree-when-it-is-read.md)
22
+ * rather than collected.
23
+ *
24
+ * ## A verdict in one direction only
25
+ *
26
+ * Three things bias the comparison, and all three bias it the same way.
27
+ *
28
+ * - **Dwell is time on screen, not time reading.** `READABLE_VISIBLE_FRACTION`
29
+ * says half of an element showing is enough ([0218](../../decisions/0218-what-a-counter-means-is-published-and-the-browser-pays-for-the-number-and-not-its-name.md)),
30
+ * so a part sits accumulating dwell while a reader reads its neighbour, and
31
+ * an ancestor accumulates dwell for the whole time any of its children was up.
32
+ * - **A word count can be a floor.** A type that declares no `copy` has words
33
+ * nothing can see (0122), and a declared prop holding something other than a
34
+ * string is a word owed and not given. Either way the part says *at least*
35
+ * this much.
36
+ * - **The reader count is generous.** `reached` is a distinct view count summed
37
+ * across rollup windows (0147), so a reader who straddled a boundary is two,
38
+ * and the mean time per reader is short by that much. This is the one of the
39
+ * three that is measured rather than argued, and {@link PaceOptions.inflation}
40
+ * is where a deployment hands the measurement in (0219).
41
+ *
42
+ * So the time a reader is credited with is generous, the words they had to get
43
+ * through are a floor, and **`skimmed` is the only verdict that survives all
44
+ * three**: it says the time on screen was short *even after* every doubt has
45
+ * been resolved in the page's favour. `paced` and `lingered` are the weaker
46
+ * claims, and where the words are a floor they are not made at all — the part
47
+ * goes back to `unknown`, with {@link PaceSilence} saying why.
48
+ *
49
+ * That asymmetry is the whole design and it is deliberate. *Readers are not
50
+ * reading this* is worth being sure of. *Readers read this* is a thing nobody
51
+ * acts on.
52
+ *
53
+ * ## Nesting, and the sums that are therefore missing
54
+ *
55
+ * A part is judged against its own subtree's words, because the words on screen
56
+ * while a band was up are the band's and its children's. So figures nest: a
57
+ * band and the paragraph inside it are both here, and the paragraph's words are
58
+ * in the band's count. Nothing on a page total adds them, and there is no
59
+ * page-wide word figure at all — one reader who scrolled past a band scrolled
60
+ * past everything in it, and a sum would charge them for it once per level.
61
+ *
62
+ * Pure, linear in the parts, and reaches no store, clock or DOM — it adds
63
+ * nothing to the broadcaster's import graph.
64
+ */
65
+ /**
66
+ * The rate a page's words are costed at, in words per minute.
67
+ *
68
+ * Published for the reason the readable fractions are (0218): a number that
69
+ * decides what a counter **means** should be quotable by the page explaining
70
+ * it, rather than retyped beside the noun it qualifies. 240 is the middle of
71
+ * the range usually reported for adult silent reading of ordinary prose, and it
72
+ * is a costing rate rather than a claim about any reader — the verdicts are
73
+ * built to survive being wrong about it by a wide margin in either direction.
74
+ *
75
+ * **Unlike the readable fractions, this one may be overridden**, and the
76
+ * difference is which side of the wire it lives on. Those two are applied in a
77
+ * browser and are baked into every counter already written. This is applied
78
+ * when the rows are read (0212), so a deployment that changes it reinterprets
79
+ * its whole history and invalidates nothing. What it may change is the rate,
80
+ * which is a fact about its own text and its own language that the framework
81
+ * cannot know; the thresholds below are the framework's statement of how much
82
+ * margin a claim needs, and are not a dial.
83
+ */
84
+ export const READING_WORDS_PER_MINUTE = 240;
85
+ /**
86
+ * Below this much of the time its words take, a part was not read.
87
+ *
88
+ * Half. Low enough that the verdict holds through all three biases above, which
89
+ * is what makes it the claim worth putting on a screen.
90
+ */
91
+ export const SKIMMED_BELOW = 0.5;
92
+ /**
93
+ * Above this much, readers stayed longer than the words account for.
94
+ *
95
+ * A weak signal by construction, because dwell counts a part that was merely up
96
+ * while something else was being read. It is a question — *is this where people
97
+ * get stuck, or is it just the tall thing at the bottom of the page* — and not
98
+ * an answer.
99
+ */
100
+ export const LINGERED_ABOVE = 3;
101
+ export const PACE_STANDINGS = everyMemberOf()([
102
+ "skimmed",
103
+ "paced",
104
+ "lingered",
105
+ "unknown",
106
+ ]);
107
+ export const PACE_SILENCES = everyMemberOf()([
108
+ "unreached",
109
+ "unreadable",
110
+ "wordless",
111
+ ]);
112
+ /** One line per standing, for a surface putting the reading in front of a person. */
113
+ export const describePaceStanding = (standing) => {
114
+ switch (standing) {
115
+ case "skimmed":
116
+ return "readers had too little time on it to have read its words";
117
+ case "paced":
118
+ return "readers had time enough for its words";
119
+ case "lingered":
120
+ return "readers stayed well past what its words account for";
121
+ case "unknown":
122
+ return "nothing could be compared";
123
+ }
124
+ };
125
+ /** One line per silence, for the same surface. */
126
+ export const describePaceSilence = (silence) => {
127
+ switch (silence) {
128
+ case "unreached":
129
+ return "no view reported it coming into view";
130
+ case "unreadable":
131
+ return "some of its words could not be read, so only a skim could be claimed";
132
+ case "wordless":
133
+ return "it says nothing that takes time to read";
134
+ }
135
+ };
136
+ const NO_STANDINGS = Object.freeze({
137
+ skimmed: 0,
138
+ paced: 0,
139
+ lingered: 0,
140
+ unknown: 0,
141
+ });
142
+ const NO_SILENCES = Object.freeze({
143
+ unreached: 0,
144
+ unreadable: 0,
145
+ wordless: 0,
146
+ });
147
+ const MS_PER_MINUTE = 60_000;
148
+ /** What a part contributes on its own: its words, and whether any of them got away. */
149
+ const ownWords = (part) => ({
150
+ words: countWords(part.copy.words),
151
+ floored: part.copy.unread.length > 0 || part.copy.unspoken.length > 0,
152
+ });
153
+ /** The totals of a part that is not there to have any, which no reading produces. */
154
+ const NOTHING_SAID = Object.freeze({ words: 0, floored: false });
155
+ /**
156
+ * Each part's subtree totals, in one pass over the reading.
157
+ *
158
+ * The parts are pre-order with depths, so a part's subtree is the run of
159
+ * following parts deeper than it — which a stack closes in constant amortised
160
+ * time per part. **Depth rather than `parentId`**, because a slot node is not a
161
+ * part and can hold element children: walking the parent chain would strand a
162
+ * whole band's words on a node this reading has never heard of, and the stack
163
+ * cannot, since it only ever asks whether the next part is deeper.
164
+ */
165
+ const subtreesOf = (parts) => {
166
+ const totals = [];
167
+ const open = [];
168
+ const close = () => {
169
+ const frame = open.pop();
170
+ if (frame === undefined)
171
+ return;
172
+ totals[frame.index] = { words: frame.words, floored: frame.floored };
173
+ const parent = open[open.length - 1];
174
+ if (parent === undefined)
175
+ return;
176
+ parent.words += frame.words;
177
+ parent.floored = parent.floored || frame.floored;
178
+ };
179
+ parts.forEach((part, index) => {
180
+ while ((open[open.length - 1]?.depth ?? -1) >= part.depth)
181
+ close();
182
+ const own = ownWords(part);
183
+ open.push({ index, depth: part.depth, words: own.words, floored: own.floored });
184
+ });
185
+ while (open.length > 0)
186
+ close();
187
+ return totals;
188
+ };
189
+ /**
190
+ * The verdict, which is the asymmetry of the module documentation written once.
191
+ *
192
+ * `skimmed` is reached before the floor is consulted, because words nobody
193
+ * counted can only make a part more skimmed than it already reads. Everything
194
+ * after that point is a claim the floor could overturn.
195
+ *
196
+ * **Published** because a comparison of two windows asks it of a pace neither
197
+ * window reported — the pace a part would have had if the change had not
198
+ * touched its words ([`pace-change.ts`](pace-change.ts)) — and a second
199
+ * spelling of this rule is the thing this subsystem has already been bitten by
200
+ * twice: two counter keys that agreed until they did not, and two word counts
201
+ * that agreed until one of them learned about slots.
202
+ */
203
+ export const paceStandingOf = (pace, floored) => {
204
+ if (pace === null)
205
+ return "unknown";
206
+ if (pace < SKIMMED_BELOW)
207
+ return "skimmed";
208
+ if (floored)
209
+ return "unknown";
210
+ return pace > LINGERED_ABOVE ? "lingered" : "paced";
211
+ };
212
+ const silenceOf = (readers, wordsWithin, floored) => {
213
+ if (readers === 0)
214
+ return "unreached";
215
+ return wordsWithin === 0 && !floored ? "wordless" : "unreadable";
216
+ };
217
+ /** A positive, finite option, or the fallback. Everything else is refused. */
218
+ const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
219
+ const pacedPart = (part, subtree, inflation, msPerWord) => {
220
+ const own = ownWords(part);
221
+ const readers = part.counters?.reached ?? 0;
222
+ const dwellMs = part.counters?.dwellMs ?? 0;
223
+ const needMs = subtree.words * msPerWord;
224
+ /**
225
+ * A page view that straddled a rollup window is one reader counted twice
226
+ * carrying one reader's dwell (0147), so the mean is short by the same
227
+ * proportion the inflation names.
228
+ * Multiplying the time is the same correction as dividing the readers and
229
+ * keeps `readers` the integer the rows actually hold.
230
+ */
231
+ const spentMs = readers === 0 ? null : (dwellMs * (1 + inflation)) / readers;
232
+ const pace = spentMs === null || needMs === 0 ? null : spentMs / needMs;
233
+ const standing = paceStandingOf(pace, subtree.floored);
234
+ return {
235
+ nodeId: part.nodeId,
236
+ type: part.type,
237
+ role: part.role,
238
+ depth: part.depth,
239
+ parentId: part.parentId,
240
+ readers,
241
+ words: own.words,
242
+ wordsWithin: subtree.words,
243
+ floored: subtree.floored,
244
+ dwellMs,
245
+ spentMs,
246
+ needMs,
247
+ pace,
248
+ standing,
249
+ silence: standing === "unknown" ? silenceOf(readers, subtree.words, subtree.floored) : null,
250
+ wordsPassed: readers * subtree.words,
251
+ };
252
+ };
253
+ /**
254
+ * The more skimmed of two, which is the ranking rule spelled once.
255
+ *
256
+ * `>` rather than `>=` is what makes *first in reading order* hold without a
257
+ * second comparison: an equal candidate never displaces the one already
258
+ * standing, and the parts arrive in reading order.
259
+ */
260
+ const worseOf = (standing, next) => standing === null || next.wordsPassed > standing.wordsPassed ? next : standing;
261
+ /**
262
+ * Whether readers had time to read what each part of a page says.
263
+ *
264
+ * Handed the output of `pageReadingOf`, because the words, the counters and the
265
+ * reading order are all already joined there and deriving them a second time is
266
+ * how two screens come to disagree.
267
+ */
268
+ export const readingPaceOf = (reading, options = {}) => {
269
+ const inflation = positive(options.inflation, 0);
270
+ const wordsPerMinute = positive(options.wordsPerMinute, READING_WORDS_PER_MINUTE);
271
+ const msPerWord = MS_PER_MINUTE / wordsPerMinute;
272
+ const subtrees = subtreesOf(reading.parts);
273
+ const parts = reading.parts.map((part, index) => pacedPart(part, subtrees[index] ?? NOTHING_SAID, inflation, msPerWord));
274
+ const standings = parts.reduce((counted, part) => ({ ...counted, [part.standing]: counted[part.standing] + 1 }), { ...NO_STANDINGS });
275
+ const silences = parts.reduce((counted, part) => part.silence === null ? counted : { ...counted, [part.silence]: counted[part.silence] + 1 }, { ...NO_SILENCES });
276
+ const whole = parts.find((part) => part.depth === 0) ?? null;
277
+ const mostSkimmed = parts.reduce((standing, next) => next.standing === "skimmed" && next !== whole ? worseOf(standing, next) : standing, null);
278
+ return {
279
+ treeId: reading.treeId,
280
+ revision: reading.revision,
281
+ views: reading.views,
282
+ parts,
283
+ standings,
284
+ silences,
285
+ whole,
286
+ mostSkimmed,
287
+ inflation,
288
+ wordsPerMinute,
289
+ };
290
+ };
291
+ //# sourceMappingURL=pace.js.map
@@ -0,0 +1,365 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { TreeId } from "../ids.js";
3
+ import type { ReaderSignalBatch } from "./signal.js";
4
+ /**
5
+ * How many page views there were — the number every rate on a screen is taken
6
+ * of, and the one number this subsystem could not state.
7
+ *
8
+ * Everything else here counts what happened *inside* a page view: time on a
9
+ * band, presses under a region, forms let go. The denominator was the summed
10
+ * `views` on a tally, which is a distinct count added across rollup windows and
11
+ * therefore generous by every page view that straddled a boundary
12
+ * ([0147](../../decisions/0147-a-rollup-is-added-to-what-is-stored-and-a-distinct-view-count-is-therefore-approximate.md)).
13
+ * 0147 bounds that error by arithmetic nobody can evaluate from the rows —
14
+ * *views per window × page-view duration ÷ window length* — so a portal showing
15
+ * a rate could say it was slightly high and never how high.
16
+ *
17
+ * **Two numbers for the same page views, counted from opposite ends.** A batch
18
+ * says whether it opened its page view (0214), which is a fact only a sender
19
+ * has, so `opened` is counted at the door, once, and never recounted. A rollup
20
+ * counts the same page views once per window they appeared in, which is
21
+ * `appearances`. For an honest sender the two differ by exactly the straddles,
22
+ * so **the over-count stops being a bound and becomes a measurement** — a
23
+ * subtraction of two stored numbers, per revision, for as long as the counters
24
+ * live.
25
+ *
26
+ * It costs no byte on the wire and no byte in a browser: the marker it reads
27
+ * already ships for the region counter, and this is the second thing derived
28
+ * from it rather than a second thing sent.
29
+ *
30
+ * **One of the two numbers now says when it was written, and the other
31
+ * deliberately does not.** `appearances` carries `foldedAt`, stamped by the
32
+ * rollup and by nothing else, because the subtraction above has a second sign:
33
+ * `opened − appearances` is the openings no fold has reached, which is the
34
+ * buffer as a number *and* what a collection that has stopped looks like. The
35
+ * row's `updatedAt` cannot tell those apart — the door writes it on every
36
+ * delivery — so the fold's own timestamp is the one thing that can, and a
37
+ * reading judges a lag against the schedule its deployment hands in
38
+ * ([0274](../../decisions/0274-a-page-view-row-says-when-the-fold-last-touched-it-and-a-stall-is-judged-against-a-schedule-the-deployment-hands-in.md)).
39
+ *
40
+ * **There is no floor here, and that is not an oversight.** A region bucket is
41
+ * floored because a country with four views in it is a person
42
+ * ([0214](../../decisions/0214-where-readers-are-is-a-floored-bucket-counted-at-the-door-and-a-page-view-says-when-it-began.md));
43
+ * a count of page views of a revision names nowhere and nobody, so there is
44
+ * nothing in it to withhold. Four page views of revision 3 is four page views
45
+ * of revision 3.
46
+ *
47
+ * **A page served in two forms has two doors, and a deployment-wide reading
48
+ * adds them.** The store keeps one row per revision per audience (0284), so a
49
+ * revision served to two audiences (0263) is counted twice over — and a reading
50
+ * that named no audience used to take whichever row came first and report the
51
+ * other as a row handed in twice, which published one form's arrivals and
52
+ * called the rest a duplicate. They add because **arrivals are people**: a
53
+ * reader who arrived arrived once whichever form they were served, so the sum
54
+ * is one deployment's arrivals and the census beside it says what it was a sum
55
+ * over (0297, 0299). It is the opposite of a page reading, where adding two
56
+ * forms' node counters would be one number about two pages (0290) — and the
57
+ * asymmetry is not a special case for arrivals but the plainest instance of the
58
+ * rule that what may be added is whatever was counted once.
59
+ */
60
+ /**
61
+ * One revision's worth of page views, as whichever side counted them.
62
+ *
63
+ * The same shape for both writers, because they are counting the same thing by
64
+ * two routes and a reading subtracts them. What the number *means* is the
65
+ * method it was handed to, which is where the two senses are named.
66
+ */
67
+ export type RevisionViews = {
68
+ readonly treeId: TreeId;
69
+ readonly revision: number;
70
+ readonly views: number;
71
+ };
72
+ /** Page views of one revision of one tree, counted from both ends. */
73
+ export type ReaderPageViews = {
74
+ readonly treeId: TreeId;
75
+ readonly revision: number;
76
+ /**
77
+ * Page views that *began* on this revision.
78
+ *
79
+ * Exact, in the sense that matters: counted once, at the instant a page view
80
+ * opened, never recounted, and therefore addable across windows, revisions,
81
+ * trees and months. The two things it is not exact against are worth knowing
82
+ * — a sender that retries an opening delivery after the first one was kept
83
+ * counts twice, and a count cannot be uncounted (0158); and a sender is what
84
+ * says it opened at all, so a page that lies inflates this the way it could
85
+ * already inflate a region bucket. The rate limiter is what bounds both.
86
+ */
87
+ readonly opened: number;
88
+ /**
89
+ * The same page views as the rollups saw them: once per window each appeared
90
+ * in.
91
+ *
92
+ * Which is why it is kept at all. On its own it is the count a rollup can
93
+ * only approximate (0147); beside `opened` it is the measurement of that
94
+ * approximation, because the only way the two can differ for an honest sender
95
+ * is a page view whose batches landed in more than one window.
96
+ */
97
+ readonly appearances: number;
98
+ };
99
+ /**
100
+ * A page-view row as the store keeps it, which is the pair, when it last moved,
101
+ * and when the fold last touched it.
102
+ */
103
+ export type StoredPageViews = ReaderPageViews & {
104
+ /** The audience these page views were served under. See `StoredTally.audienceId` (0284). */
105
+ readonly audienceId: AudienceId;
106
+ /**
107
+ * When either writer last moved this row.
108
+ *
109
+ * Written by the door on every delivery that opened a page view *and* by
110
+ * every rollup that folded one, which is what makes it useless for telling a
111
+ * stalled collection from a quiet one: a busy page whose rollup has stopped
112
+ * keeps a fresh timestamp while its appearances never move again.
113
+ */
114
+ readonly updatedAt: string;
115
+ /**
116
+ * When a rollup last folded a window holding page views of this revision, or
117
+ * absent where nothing attests a fold.
118
+ *
119
+ * **Absent is not *never folded*.** It is *nothing here can say*: a row
120
+ * written before the column existed, a store a caller built by hand, a
121
+ * fixture. The two cases are one state, no reading claims anything from it,
122
+ * and the first fold after an upgrade fills it in (0274).
123
+ *
124
+ * Where it *is* there, it is the one timestamp in this subsystem written by a
125
+ * single writer, and therefore the only thing that can say an opening has
126
+ * been pending longer than it should be.
127
+ */
128
+ readonly foldedAt?: string;
129
+ };
130
+ /**
131
+ * The page views a delivery opened, per revision, deduplicated by view key.
132
+ *
133
+ * The dedup inside the delivery is load-bearing rather than defensive: a sender
134
+ * draining a queue after an outage posts what it has, which may include an
135
+ * opening batch it already sent and could not confirm, and a page view counted
136
+ * twice cannot be uncounted
137
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
138
+ * Keys are compared rather than batches, so one opening delivered twice is one
139
+ * page view and two page views opened in one delivery are two.
140
+ *
141
+ * A batch that opened nothing adds nothing, and a sender that never says adds
142
+ * nothing at all — a batch synthesised on a server or replayed from a fixture
143
+ * is not an arrival, exactly as it is not a view (0146). The parser has already
144
+ * refused a batch that claims an opening and names no page view, so a key is
145
+ * always there to compare when the claim is.
146
+ *
147
+ * Pure, and shared: the region counter stamps a country onto these rows rather
148
+ * than walking the delivery itself, which is what keeps the two counters from
149
+ * disagreeing about how many readers arrived.
150
+ */
151
+ export declare const openingsOf: (batches: readonly ReaderSignalBatch[]) => readonly RevisionViews[];
152
+ /**
153
+ * One revision, as a reading reports it — the stored row, and what subtracting
154
+ * its two numbers says.
155
+ *
156
+ * `updatedAt` travels with it because a page-view figure that has not moved in a
157
+ * day is a fact about the deployment rather than about its readers, and a screen
158
+ * showing the number should be able to say when it last did.
159
+ */
160
+ export type RevisionPageViews = ReaderPageViews & {
161
+ /**
162
+ * The audience this reading is of, or `null` where it is of every form the
163
+ * window held.
164
+ *
165
+ * The same three-valued field `RegionReading.audienceId` is, and the
166
+ * same rule: it is what the *asking* named and never what the rows turned out
167
+ * to say. One row naming one form is not a reading of one form — a window may
168
+ * simply hold one today — so a single-membered census does not fill this in
169
+ * (0297, 0299).
170
+ */
171
+ readonly audienceId: AudienceId | null;
172
+ /**
173
+ * The audiences whose rows were added into this reading, deduplicated and in
174
+ * a stable order.
175
+ *
176
+ * `[]` where the rows named none, one name where this is one form's door, and
177
+ * **more than one where it is a sum over forms, which is a measurement rather
178
+ * than a fault**: a page served in two forms (0263) has two door rows (0284),
179
+ * and a reader who arrived arrived once whichever form they were served, so
180
+ * the sum is one deployment's arrivals (0297, 0299). Compare a page reading,
181
+ * where adding two forms' node counters is one number about two pages and
182
+ * `PageHealth` calls it `audiences-mixed` (0290).
183
+ */
184
+ readonly audiences: readonly AudienceId[];
185
+ /**
186
+ * When either writer last moved a row behind this reading — the newest of
187
+ * them where it is a sum, because the question is when the number last
188
+ * changed and the busiest form is what last changed it.
189
+ *
190
+ * See {@link StoredPageViews.updatedAt} for why it cannot tell a stalled
191
+ * collection from a quiet one.
192
+ */
193
+ readonly updatedAt: string;
194
+ /**
195
+ * The fold this reading is waiting on: the oldest fold attested by a row that
196
+ * still has openings pending, or the oldest attested of them all where none
197
+ * has, and absent where nothing attests one.
198
+ *
199
+ * For one form's door that is simply {@link StoredPageViews.foldedAt}. For a
200
+ * sum over forms it is the only choice that keeps a fault from hiding behind
201
+ * a busier form — a fold that ran a minute ago on one form cannot vouch for a
202
+ * form whose openings have been waiting a day — and it is *the oldest of the
203
+ * rows still waiting* rather than the oldest of all of them so that a quiet
204
+ * form with nothing pending cannot invent a stall. A summed door is therefore
205
+ * stalled exactly when one of its forms is (0299).
206
+ */
207
+ readonly foldedAt?: string;
208
+ /**
209
+ * Appearances in excess of openings — the over-count in every distinct view
210
+ * count stored against this revision, measured rather than bounded.
211
+ *
212
+ * Never negative: a reading taken between a door write and the next rollup
213
+ * sees openings the counters have not met yet, and that is `pending` rather
214
+ * than a negative drift.
215
+ */
216
+ readonly drift: number;
217
+ /**
218
+ * Page views that began and whose batches no rollup has folded yet — the
219
+ * buffer, as a number.
220
+ *
221
+ * It is the other sign of the same subtraction, so **one form's door never
222
+ * has both** — and a door summed over two forms can, because the two are
223
+ * added per row rather than taken from the two sums (0299): one form
224
+ * mid-collection and one form with straddles is a revision with six of each,
225
+ * and netting them would report it as exactly measured, which neither form
226
+ * is. A reading that showed neither would make a deployment whose collection
227
+ * has stopped look like a deployment whose readers had left.
228
+ */
229
+ readonly pending: number;
230
+ /**
231
+ * `drift ÷ opened`: how generous the distinct counts against this revision
232
+ * are, as a fraction. `null` when nothing has opened, because the question
233
+ * has no answer rather than the answer nought.
234
+ */
235
+ readonly inflation: number | null;
236
+ };
237
+ export type PageViewReading = {
238
+ /** Page views that began, across every row read. Exact, and addable. */
239
+ readonly opened: number;
240
+ readonly appearances: number;
241
+ readonly drift: number;
242
+ readonly pending: number;
243
+ readonly inflation: number | null;
244
+ /** Newest revision first, trees in id order, so a screen does not reorder on a refresh. */
245
+ readonly revisions: readonly RevisionPageViews[];
246
+ };
247
+ /**
248
+ * Rows from the store, read as something a screen may show.
249
+ *
250
+ * **Totalled from the rows and never from the totals.** `drift` on the whole
251
+ * reading is the sum of each revision's drift, not the difference of the two
252
+ * sums: a revision mid-collection has openings the rollups have not reached,
253
+ * and subtracting in the aggregate would let that cancel another revision's
254
+ * straddles and report a page as more exact than any part of it is.
255
+ *
256
+ * Unlike a region reading this withholds nothing, groups nothing, and hides
257
+ * nothing. Every row is already an aggregate about a revision of a tree.
258
+ */
259
+ export declare const pageViewReadingOf: (rows: readonly StoredPageViews[]) => PageViewReading;
260
+ /**
261
+ * The page-view row a reading of one revision should be divided by, picked out
262
+ * of a window of rows.
263
+ *
264
+ * **This exists because the pairing is the part that can be got wrong, and it
265
+ * fails quietly.** The number a correction wants belongs to *one revision of
266
+ * one page*; the obvious thing to reach for is the aggregate
267
+ * {@link PageViewReading.inflation} published beside it, and handing a busy
268
+ * page's straddle rate to a quiet one is an invented correction with three
269
+ * decimal places on it. Nothing would fail — the figures downstream would
270
+ * simply be a little wrong, in whichever direction their own safety argument
271
+ * needs them right. So the rule lives once, here, beside the counter it is a
272
+ * rule about, rather than four lines in every consumer.
273
+ *
274
+ * **It filters rather than trusts its caller, and says what it dropped.** A
275
+ * caller who handed in a whole store's rows and one who handed in the wrong
276
+ * revision's look identical from the inside, so both are counted.
277
+ */
278
+ export type PageViewsFor = {
279
+ /**
280
+ * This revision's door, read through {@link pageViewReadingOf}, or `null`
281
+ * where this revision has none.
282
+ *
283
+ * Read through the reading rather than subtracted again, because one
284
+ * definition of drift, pending and inflation is the point: a second would be
285
+ * a second place for them to disagree with the counter they describe.
286
+ *
287
+ * **Where the asking names no audience this is the sum of every form's
288
+ * door**, and it was once whichever form came first in the caller's array
289
+ * (0299). A page served in two forms has two door rows (0263, 0284), so a
290
+ * deployment-wide asking was answered with one form's openings and the other
291
+ * form's reported as a row handed in twice — the same quiet undercount found
292
+ * in the reading beside it (0297). Arrivals add because arrivals are people:
293
+ * a reader who arrived arrived once whichever form they were served.
294
+ * {@link RevisionPageViews.audiences} is what the sum was over.
295
+ */
296
+ readonly measured: RevisionPageViews | null;
297
+ /**
298
+ * Rows for another tree or another revision, and ignored.
299
+ *
300
+ * Dividing one revision's counters by another's readers is the mistake that
301
+ * would make every rate taken off them quietly wrong.
302
+ */
303
+ readonly foreign: number;
304
+ /**
305
+ * Rows for this tree and revision, in another audience, and ignored.
306
+ *
307
+ * A page is served in as many forms as it has audiences (0263) and the door
308
+ * counts each one's arrivals on its own row (0284), so a window holding two
309
+ * of them is a deployment doing what it was built to do. It is `foreign` to
310
+ * nothing and `duplicated` to nothing: the other form's readers are real and
311
+ * are simply not the ones this reading is of.
312
+ */
313
+ readonly otherAudience: number;
314
+ /**
315
+ * Rows for this tree, revision **and audience** beyond the first of that
316
+ * audience, where every one after it was ignored.
317
+ *
318
+ * A store keeps one row per revision per audience, so this cannot happen from
319
+ * one read — it happens when a caller concatenates two. Adding them is wrong,
320
+ * because the openings are already a running total and would double (0158);
321
+ * taking the last is wrong, because it is not the truer one. So the first row
322
+ * of each form stands and the fact is reported.
323
+ *
324
+ * **The audience is part of what makes two rows two rows**, and leaving it
325
+ * out was an undercount (0299): two forms' doors keyed by nothing at all made
326
+ * the second form a repeat of the first, so a deployment-wide reading
327
+ * published one form's arrivals and called the rest a duplicate. A form's own
328
+ * door was never affected — the audience is picked before this, so one form's
329
+ * rows key the same either way.
330
+ */
331
+ readonly duplicated: number;
332
+ };
333
+ /**
334
+ * A revision of a tree, and the audience the asking is about.
335
+ *
336
+ * The audience is optional and `null` means the same as absent: *this caller
337
+ * did not say*, which reads every form of the page and is what a window
338
+ * written before 0284 and every reading taken before this rule has always
339
+ * done. A caller that names one — which `PageReading` now does for itself —
340
+ * gets that form's door row and nothing else.
341
+ */
342
+ export type RevisionOf = {
343
+ readonly treeId: TreeId;
344
+ readonly revision: number;
345
+ readonly audienceId?: AudienceId | null;
346
+ };
347
+ /**
348
+ * Read one revision's door out of a window of rows.
349
+ *
350
+ * Linear in the rows, with one pass and one map.
351
+ */
352
+ export declare const pageViewsFor: (where: RevisionOf, rows: readonly StoredPageViews[]) => PageViewsFor;
353
+ /**
354
+ * The straddle correction for one revision of one page: `drift ÷ opened` off
355
+ * that page's own door — its own form's row where the asking names an audience,
356
+ * and the sum of every form's where it names none (0299).
357
+ *
358
+ * The number `PaceOptions.inflation` wants, published so that a consumer
359
+ * holding a window of counters over several pages does not write the matching
360
+ * itself. `null` where there is no row for the revision, or where nothing has
361
+ * opened — which is *the question has no answer* rather than *the answer is
362
+ * nought*, and is the reason this is not simply `0`.
363
+ */
364
+ export declare const inflationFor: (where: RevisionOf, rows: readonly StoredPageViews[]) => number | null;
365
+ //# sourceMappingURL=page-views.d.ts.map