@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
@@ -3,32 +3,41 @@ import { clampLimit } from "../paging.js";
3
3
  import { systemClock } from "../runtime/events.js";
4
4
  import { rollUp } from "./rollup.js";
5
5
  /**
6
- * The one operation that empties the buffer.
6
+ * The one operation that counts the buffer.
7
7
  *
8
8
  * `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
9
9
  * keep what the fold produced — and until this module existed nothing joined
10
10
  * the three, so a deployment with signals switched on accumulated the largest
11
11
  * table it owns and counted none of it.
12
12
  *
13
- * **Counting and forgetting are one call, and that is the design rather than a
14
- * convenience.** A rollup reports *what this window added* (0147), so a batch
15
- * counted twice is counted twice forever: there is no idempotence to fall back
16
- * on and no way to notice afterwards, because the wrong number looks exactly
17
- * like a busy afternoon. The only defence that does not need durable bookkeeping
18
- * is for the set of batches rolled up and the set forgotten to be the same set,
19
- * decided once, in one place. That is this file, and it is why there is no
20
- * exported `applyReaderSignalRetention` beside it — a function that can forget
21
- * without counting is the data-loss bug, and one that can count without
22
- * forgetting is the double-count bug.
13
+ * **Counting and recording that it happened are one call, and that is the
14
+ * design rather than a convenience.** A rollup reports *what this window
15
+ * added* (0147), so a batch counted twice is counted twice forever: there is no
16
+ * idempotence to fall back on and no way to notice afterwards, because the
17
+ * wrong number looks exactly like a busy afternoon. The only defence that does
18
+ * not need durable bookkeeping is for the set of batches rolled up and the set
19
+ * marked as counted to be the same set, decided once, in one place. That is
20
+ * this file.
21
+ *
22
+ * **Until 5 November the mark was a delete** (0146), and the sentence above
23
+ * said *forgotten* where it now says *marked*. A delivery is now kept for the
24
+ * window its deployment states — thirty days by default, so that an operator
25
+ * can look at individual deliveries rather than only at counters (0349) — and
26
+ * deleted by a second sweep in `expire.ts`. What did not change is the thing
27
+ * the invariant protects: this run decides one prefix, counts it, and records
28
+ * that it counted it, and no other operation may touch that decision. What that
29
+ * split buys is that the two failures are no longer the same failure. A sweep
30
+ * that deletes without counting loses deliveries; this cannot delete at all.
23
31
  *
24
32
  * Nothing schedules it, for the reason nothing schedules telemetry's retention
25
- * or `auditSnapshot`: when a deployment forgets is an operational choice, and a
26
- * framework that quietly deleted a host's data on a timer it chose would be
27
- * making it. A host calls this from a cron route, a deploy hook, or by hand.
33
+ * or `auditSnapshot`: when a deployment counts is an operational choice, and a
34
+ * framework that quietly swept a host's data on a timer it chose would be
35
+ * making it. A host calls this from a cron route, a deploy hook, or by hand,
36
+ * and calls {@link expireReaderEvents} from the same place.
28
37
  *
29
38
  * **One run at a time, and the caller is what makes that true.** Two runs over
30
39
  * the same ripe prefix both roll it up and both apply; applying is additive
31
- * (0147), so the counters double and the buffer empties once, leaving nothing
40
+ * (0147), so the counters double and the prefix is marked once, leaving nothing
32
41
  * behind that could say what happened. Nothing here can prevent it — a journal
33
42
  * and a store are two handles with no shared transaction between them — so
34
43
  * serialising belongs to whatever schedules this. `apps/loom/scripts/
@@ -36,19 +45,34 @@ import { rollUp } from "./rollup.js";
36
45
  * cheapest thing that works for a cron that overruns its own interval.
37
46
  */
38
47
  /**
39
- * The window is the age a batch reaches before it is counted and dropped, and
40
- * it is two arguments pulling opposite ways.
48
+ * The window is the age a batch reaches before it is counted, and it is two
49
+ * arguments pulling opposite ways.
41
50
  *
42
51
  * **Longer is more accurate.** `views` and `reached` count distinct page views,
43
52
  * distinctness does not add up, and a page view whose batches straddle two
44
53
  * windows is counted in both — the over-count 0147 accepts. `tally.ts` already
45
54
  * states the remedy in its own words: *a deployment that wants the bound small
46
55
  * makes the rollup window long relative to a page view.* This is that number.
56
+ * A deployment no longer has to guess whether it chose well: each run adds its
57
+ * window's page views to the counter the door counts arrivals into, so the
58
+ * difference between the two is what this setting actually cost
59
+ * (`page-views.ts`).
60
+ *
61
+ * **A run also writes down that it happened.** Applying a window stamps the
62
+ * fold's own timestamp on each revision's door row, which is what lets a
63
+ * deployment be told that nothing has folded for longer than its own schedule
64
+ * allows — the openings waiting are otherwise indistinguishable from the
65
+ * ordinary one-window lag this setting creates (0274).
47
66
  *
48
- * **Shorter is more anonymous.** The raw window is the entire mechanism by
49
- * which a view key stops existing (0146). The key is opaque, random and
50
- * correlates nothing outside the buffer, but it correlates that, and the
51
- * argument for it rests on how briefly it lives.
67
+ * **Shorter is more anonymous — and since 5 November this is no longer the
68
+ * window that governs that.** The view key stops existing when the row holding
69
+ * it is deleted, and that is now the kept window rather than this one
70
+ * (0349, 0351): a delivery is counted at this age and deleted at the age
71
+ * `expire.ts` is given. This setting still decides how much over-count a
72
+ * straddling page view causes, which is the accuracy argument above; what it no
73
+ * longer decides is how long a page view's signals stay correlatable. That
74
+ * number is `DEFAULT_READER_EVENT_RETENTION_MS` and the tension in it is
75
+ * recorded rather than hidden.
52
76
  *
53
77
  * An hour is long against a page view and short against a day, which is why it
54
78
  * is the default rather than a constant: rule 5 of `docs/signals.md` makes the
@@ -91,6 +115,27 @@ export const collectionPlanOf = (scanned, horizon) => {
91
115
  waiting: scanned.length - ripe.length,
92
116
  };
93
117
  };
118
+ /**
119
+ * The pairs a run folding a window that **begins** at `from` may ask, and the
120
+ * count of the ones it may not.
121
+ *
122
+ * The comparison is against the oldest delivery in the window rather than
123
+ * against the run's own clock, and that is the whole of the rule: every
124
+ * delivery this run folds arrived at or after `from`, so a question whose start
125
+ * is at or before `from` is answered over readers who all arrived after it was
126
+ * asked. A question asked in the middle of a window is held back one run, which
127
+ * costs one window of an answer and buys a figure that means what its label
128
+ * says.
129
+ *
130
+ * **An unreadable instant withholds every question with a start**, because the
131
+ * fallback is the one that cannot be noticed: counting a step from a window
132
+ * nobody can place is a figure nobody can date.
133
+ */
134
+ export const funnelsAskedOf = (pairs, from) => {
135
+ const begins = Date.parse(from);
136
+ const asking = pairs.filter(({ countedFrom }) => countedFrom === undefined || (Number.isFinite(begins) && countedFrom <= begins));
137
+ return { asking, withheld: pairs.length - asking.length };
138
+ };
94
139
  export const horizonOf = (configured, now) => {
95
140
  const instant = Date.parse(now);
96
141
  return Number.isFinite(instant) ? new Date(instant - configured.windowMs).toISOString() : null;
@@ -101,6 +146,12 @@ export const horizonOf = (configured, now) => {
101
146
  * Every batch from the horizon on is too young to count, and `collectionPlanOf`
102
147
  * needs only the first of them to know where the ripe prefix ends — so reading
103
148
  * further would be reading the busiest part of the table to throw it away.
149
+ *
150
+ * **Uncounted rows only** (0351), which is what makes the oldest end of the
151
+ * table the oldest *uncounted* delivery rather than the oldest kept one. Without
152
+ * it this scan would read the whole kept window — thirty days by default — to
153
+ * reach the handful of rows a run is for, and the cost of collecting would grow
154
+ * with a setting that has nothing to do with collecting.
104
155
  */
105
156
  const scanFrom = async (journal, horizon, scanLimit) => {
106
157
  const collected = [];
@@ -108,6 +159,7 @@ const scanFrom = async (journal, horizon, scanLimit) => {
108
159
  while (collected.length < scanLimit) {
109
160
  const page = await journal.read({
110
161
  direction: "newer",
162
+ counted: false,
111
163
  limit: Math.min(SCAN_PAGE, scanLimit - collected.length),
112
164
  ...(cursor ? { cursor } : {}),
113
165
  });
@@ -124,11 +176,12 @@ const scanFrom = async (journal, horizon, scanLimit) => {
124
176
  return { ok: true, batches: collected, full: true };
125
177
  };
126
178
  /**
127
- * Count a window of the buffer into the durable counters, then drop it.
179
+ * Count a window of the buffer into the durable counters, then record that it
180
+ * was counted.
128
181
  *
129
182
  * The order is the safe one and the reverse is a data-loss bug that looks like
130
- * a feature working: aggregates first, the buffer second. What that leaves is
131
- * `counted-not-forgotten`, which is visible and recoverable — the opposite
183
+ * a feature working: aggregates first, the mark second. What that leaves is
184
+ * `counted-not-recorded`, which is visible and recoverable — the opposite
132
185
  * order's failure is neither.
133
186
  */
134
187
  export const collectReaderSignals = async (journal, store, request = {}) => {
@@ -149,44 +202,139 @@ export const collectReaderSignals = async (journal, store, request = {}) => {
149
202
  const plan = collectionPlanOf(scanned.batches, horizon);
150
203
  if (plan.before === null)
151
204
  return { outcome: "nothing-ripe", waiting: plan.waiting };
152
- const rollup = rollUp(plan.ripe, { ...(request.pairs ? { pairs: request.pairs } : {}) });
205
+ /**
206
+ * **One fold per audience, not one per window** (0284).
207
+ *
208
+ * A window holds whatever arrived in it, and once a deployment serves two
209
+ * forms of a page that is two audiences' batches interleaved. Folding them
210
+ * together would add two populations into one counter — the failure the
211
+ * record behind this exists to prevent, and the one that cannot be undone
212
+ * afterwards, because the rows that would say which form a reader saw are the
213
+ * rows being summed.
214
+ *
215
+ * So the ripe batches are grouped by the audience they were filed under and
216
+ * each group is folded on its own, then **all of them are written together**
217
+ * (0316). `rollUp` stays audience-blind: it is handed one audience's batches
218
+ * and knows nothing about the dimension, which is what keeps the fold a pure
219
+ * function of a window.
220
+ *
221
+ * The summary adds up across audiences, because it describes the run rather
222
+ * than any one population.
223
+ */
224
+ const byAudience = new Map();
225
+ for (const batch of plan.ripe) {
226
+ const group = byAudience.get(batch.audienceId);
227
+ if (group === undefined)
228
+ byAudience.set(batch.audienceId, [batch]);
229
+ else
230
+ group.push(batch);
231
+ }
232
+ /**
233
+ * The oldest delivery in the buffer, which is the first batch the scan read:
234
+ * it runs from the oldest end and the ripe prefix starts there.
235
+ *
236
+ * There is always one wherever a summary is built — `plan.before` is a
237
+ * position taken off the last ripe batch, so a plan carrying one has a first
238
+ * — and the unreachable branch is a parse of nothing rather than a nought on
239
+ * purpose. A nought would say *a delivery that arrived this instant*, which
240
+ * is the strongest answer the retention reading can give; a figure that is
241
+ * not a number makes it answer that nothing here can say.
242
+ */
243
+ const oldest = plan.ripe[0]?.receivedAt ?? "";
244
+ /**
245
+ * The questions this window is old enough to answer, decided once for the
246
+ * whole run (0418) — every audience's fold asks the same ones, because a
247
+ * start is a fact about when somebody asked and not about who read.
248
+ */
249
+ const { asking, withheld } = funnelsAskedOf(request.pairs ?? [], oldest);
250
+ const folded = [...byAudience].map(([audience, batches]) => ({
251
+ audience,
252
+ rollup: rollUp(batches, { ...(asking.length > 0 ? { pairs: asking } : {}) }),
253
+ }));
153
254
  const summary = {
154
255
  counted: plan.ripe.length,
155
- tallies: rollup.tallies.length,
156
- funnels: rollup.funnels.length,
157
- views: rollup.views,
158
- uncorrelated: rollup.uncorrelated,
256
+ withheldFunnels: withheld,
257
+ oldestMs: Date.parse(now) - Date.parse(oldest),
258
+ tallies: folded.reduce((total, { rollup }) => total + rollup.tallies.length, 0),
259
+ acted: folded.reduce((total, { rollup }) => total + rollup.acted.length, 0),
260
+ funnelHours: folded.reduce((total, { rollup }) => total + rollup.funnelHours.length, 0),
261
+ funnels: folded.reduce((total, { rollup }) => total + rollup.funnels.length, 0),
262
+ views: folded.reduce((total, { rollup }) => total + rollup.views, 0),
263
+ uncorrelated: folded.reduce((total, { rollup }) => total + rollup.uncorrelated, 0),
264
+ redelivered: folded.reduce((total, { rollup }) => total + rollup.redelivered, 0),
159
265
  };
160
- const applied = await store.apply(rollup, now);
266
+ /**
267
+ * **One write for the whole window, every audience in it** (0316).
268
+ *
269
+ * One call per audience is what this was, and it had a state between the
270
+ * calls that nothing could get out of: the audiences already applied were
271
+ * durable, the rest were not, and the buffer still held the window — because
272
+ * counting and forgetting are one operation, which is the invariant at the
273
+ * top of this file. So the next run folded the same batches again and **added
274
+ * the already-durable audiences a second time**, permanently (0158), on the
275
+ * five of nine counters that are occurrences rather than distinct counts.
276
+ * `unavailable` said *nothing became durable* while that was happening.
277
+ *
278
+ * It is one `applyWindow` now, so there is no state to get out of and the
279
+ * sentence on `unavailable` is true again. Nothing is reported about it
280
+ * because there is nothing left to report.
281
+ */
282
+ const applied = await store.applyWindow(folded.map(({ audience, rollup }) => ({
283
+ audience,
284
+ tallies: rollup.tallies,
285
+ funnels: rollup.funnels,
286
+ appearances: rollup.appearances,
287
+ acted: rollup.acted,
288
+ funnelHours: rollup.funnelHours,
289
+ })), now);
161
290
  if (!applied.ok)
162
291
  return { outcome: "unavailable", error: applied.error };
163
- const forgotten = await journal.forget({ before: plan.before });
164
- if (!forgotten.ok) {
292
+ /**
293
+ * The same instant the counters were written with, so one run leaves one
294
+ * instant across both halves of what it did — and the instant a reading of
295
+ * the fold's lag is taken against is the instant the fold actually happened.
296
+ */
297
+ const recorded = await journal.counted({ before: plan.before, at: now });
298
+ if (!recorded.ok) {
165
299
  return {
166
- outcome: "counted-not-forgotten",
300
+ outcome: "counted-not-recorded",
167
301
  summary,
168
302
  before: plan.before,
169
- error: forgotten.error,
303
+ error: recorded.error,
170
304
  };
171
305
  }
172
306
  return {
173
307
  outcome: "collected",
174
308
  summary,
175
- removed: forgotten.value.removed,
309
+ recorded: recorded.value.counted,
176
310
  more: scanned.full,
177
311
  };
178
312
  };
179
313
  const batches = (count) => `${count} ${count === 1 ? "batch" : "batches"}`;
180
314
  const uncorrelated = (summary) => summary.uncorrelated === 0 ? "" : `, ${summary.uncorrelated} with no view key`;
315
+ /**
316
+ * Said only when there were some, in the same clause-after-the-count shape
317
+ * `uncorrelated` uses, because a line that always carries a nought trains an
318
+ * operator to stop reading it.
319
+ */
320
+ const redelivered = (summary) => summary.redelivered === 0 ? "" : `, ${summary.redelivered} delivered again and folded once`;
321
+ /**
322
+ * Said only when there were some, like the two above, and said as *this window
323
+ * is too old for them* rather than as a refusal: the questions are fine and the
324
+ * next window answers them (0418).
325
+ */
326
+ const withheldFunnels = (summary) => summary.withheldFunnels === 0
327
+ ? ""
328
+ : `, ${summary.withheldFunnels} ${summary.withheldFunnels === 1 ? "funnel" : "funnels"} not asked of a window older than them`;
181
329
  /** One line for an operator, because an outcome nobody can read is one nobody acts on. */
182
330
  export const describeCollection = (outcome) => {
183
331
  switch (outcome.outcome) {
184
332
  case "collected":
185
- return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}, and forgot ${outcome.removed}${outcome.more ? " — more is waiting" : ""}`;
333
+ return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}${redelivered(outcome.summary)}${withheldFunnels(outcome.summary)}, and marked ${outcome.recorded} counted${outcome.more ? " — more is waiting" : ""}`;
186
334
  case "nothing-ripe":
187
335
  return `nothing old enough to count${outcome.waiting === 0 ? "" : `, ${batches(outcome.waiting)} waiting`}`;
188
- case "counted-not-forgotten":
189
- return `counted ${batches(outcome.summary.counted)} and could not forget them, so the next run counts them again unless the buffer is pruned below ${outcome.before}: ${outcome.error.detail}`;
336
+ case "counted-not-recorded":
337
+ return `counted ${batches(outcome.summary.counted)} and could not record it, so the next run counts them again unless they are marked counted below ${outcome.before}: ${outcome.error.detail}`;
190
338
  case "refused":
191
339
  return `collection refused: ${outcome.reason}`;
192
340
  case "unavailable":
@@ -0,0 +1,348 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { TreeId } from "../ids.js";
3
+ import type { FunnelReach, PairReach } from "./funnel.js";
4
+ /**
5
+ * Which of a deployment's pages loses the most readers between an ask and its
6
+ * answer.
7
+ *
8
+ * A deployment can already ask where its readers stop reading, and the pages
9
+ * come back in one order with the worst of them named
10
+ * ([0250](../../decisions/0250-a-deployment-is-ordered-by-readers-lost-at-the-doors-scale-and-a-page-the-door-cannot-scale-is-out-of-the-order.md)).
11
+ * It could not ask where its readers stop **converting**, and the two are not
12
+ * the same question: a pricing band every reader reaches and nobody buys from
13
+ * has no fall in it anywhere, so the order of falls says *nothing to do here*
14
+ * about the half of a page that pays.
15
+ *
16
+ * This is that second order, over the funnel answers a deployment already has:
17
+ * no payload field, no counter, no column, no byte on any wire and no figure a
18
+ * funnel reading does not already publish.
19
+ *
20
+ * ## It ranks the loss between the two ends and never the loss before them
21
+ *
22
+ * A funnel answer holds two losses. Readers who never reached the first end are
23
+ * `before`, and readers who reached it and did not finish are `between`
24
+ * (0221, 0229). **Only the second is ranked here**, and that is the whole of
25
+ * what keeps this order and the order of falls from being two spellings of one
26
+ * list: a reader who never reached the ask stopped *reading*, which is where
27
+ * the fall between two siblings already puts them, and a page whose readers
28
+ * stop short of the pricing band would otherwise stand near the head of both
29
+ * orders for one event.
30
+ *
31
+ * So the key is `reached − converted`, put on the scale that page's own door
32
+ * counts in by `atDoorScale`, because the straddle rate is each page's own and
33
+ * ranking the raw losses would rank partly by how long readers stay (0219).
34
+ *
35
+ * ## The key is a ceiling, and the floor beside it is published
36
+ *
37
+ * That key is the **most** the leak could be rather than an estimate of it. The
38
+ * straddle inflates both counts of the subtraction and scaling puts that back,
39
+ * but a straddle also splits a conversion across two windows and **loses** it
40
+ * (0147) — and no division puts back a count that was never made. So
41
+ * {@link LeakingPage.readers} is a ceiling, {@link LeakingPage.readersAtLeast}
42
+ * is the floor underneath it, and the two meet wherever nobody's visit spanned
43
+ * two windows. Both come off {@link PairLeak}, which is where the bounds the
44
+ * funnel already published are joined to the door's scale.
45
+ *
46
+ * What the floor buys is the one sentence this order could not say before: *this
47
+ * page is losing at least this many readers, however short your rollup window
48
+ * is.* It is also what makes {@link DeploymentConversion.worstSecure}
49
+ * answerable — whether the page named first is first however the straddle fell,
50
+ * which a ranking on a ceiling alone cannot say.
51
+ *
52
+ * ## One argument, because the funnel answer already carries the door
53
+ *
54
+ * The order of falls takes the door rows beside the readings, since a reading
55
+ * of where reading stops holds no arrivals. A funnel answer holds both — it is
56
+ * read against the exact number of readers the revision had — so this is one
57
+ * call with one argument and there is no row set to match up wrongly.
58
+ *
59
+ * ## A page nobody asked anything of is not a page nobody answered
60
+ *
61
+ * Nine states keep a page out of the order and each is a different sentence.
62
+ * Three are the door's (0229); one is the caller's window holding two forms and
63
+ * naming neither (0300); one is a question nobody has reached; one is a count
64
+ * that cannot be reconciled with the page views there were to hold it; one is
65
+ * the page that leaks nobody; and **two are about the questions a deployment
66
+ * wrote rather than about any measurement** — a revision with no funnel
67
+ * question at all, and a revision all of whose questions name parts it no
68
+ * longer has (0212). No reading before this one could report either of those
69
+ * two, because no reading before this one was keyed by what a deployment asked.
70
+ *
71
+ * ## What is deliberately not published
72
+ *
73
+ * **No deployment-wide conversion rate.** The artefact is an order and not a
74
+ * total: a rate over several pages would need a denominator across them, and
75
+ * the readers of two pages are two populations whose funnel answers are added
76
+ * across rollup windows and therefore generous (0147). Every reader figure here
77
+ * is one page's own, on that page's own row.
78
+ *
79
+ * The one figure that is added is `arrivals`, addable for the reason every
80
+ * other counter here is not: a page view began on exactly one revision of
81
+ * exactly one tree, was counted once at the door, and is never recounted
82
+ * (0219). The counts of questions add for the same kind of reason — a question
83
+ * belongs to one revision of one page.
84
+ *
85
+ * Pure, linear in the readings times their pairs, and reaches no store, clock
86
+ * or DOM.
87
+ */
88
+ /** A reason a page's conversion loss is withheld rather than ranked. */
89
+ export type ConversionSilence =
90
+ /**
91
+ * The reading holds two forms of the page and named neither, so it read
92
+ * neither population's answers.
93
+ *
94
+ * Checked before everything else, because it is the cause of the noughts
95
+ * underneath it: two forms of a page share a tree and a revision (0263) and
96
+ * are told apart by a column (0284), so a funnel answer handed both with
97
+ * neither asked for reads no pair at all — which is indistinguishable from a
98
+ * page nothing asks anything of, and would be published as one (0301).
99
+ *
100
+ * The remedy is the caller's and it is the only one here that is: split the
101
+ * window by audience and read each form on its own.
102
+ */
103
+ "unsplit"
104
+ /**
105
+ * There is no page-view row at the door for this revision, so its loss cannot
106
+ * be put on the same scale as another page's.
107
+ *
108
+ * Not a page that was not measured. Every figure inside its funnel answer
109
+ * stands; what is missing is the one number that makes two pages comparable.
110
+ */
111
+ | "unscaled"
112
+ /**
113
+ * The row is there and nothing in it says a page view ever began.
114
+ *
115
+ * Either nobody read this revision, or the senders are not marking their
116
+ * openings — and the reading publishes both counts, so the diagnosis is a
117
+ * subtraction a surface can make.
118
+ */
119
+ | "unopened"
120
+ /** Readers arrived and no rollup has folded a window of their reading yet. */
121
+ | "uncounted"
122
+ /**
123
+ * Every question this revision is asked names a part it no longer has.
124
+ *
125
+ * Removed by a change, renamed, or moved to another tree: the counts against
126
+ * those ends cannot move again and the noughts they report are not reader
127
+ * facts (0212). **The sentence a surface should print is not about readers at
128
+ * all** — it is *re-point these questions* — which is why this is held apart
129
+ * from a funnel nobody answered.
130
+ *
131
+ * Reported only where **every** question is stale. A revision with one sound
132
+ * question and three stale ones is ranked on the sound one, with the three
133
+ * counted on the row.
134
+ */
135
+ | "stale"
136
+ /**
137
+ * Nobody reached the start of any question this revision is asked.
138
+ *
139
+ * The questions name parts the page has and no reader has got to one of them
140
+ * in this window. There is no conversion to lose rather than a conversion
141
+ * everybody failed, and the two print as opposite sentences.
142
+ */
143
+ | "unanswered"
144
+ /**
145
+ * More readers reached its sharpest ask than have ever appeared on the page.
146
+ *
147
+ * No rollup produces this: a view that satisfied an end in a window is a view
148
+ * that appeared in it. A funnel row older than the page-view column, or a
149
+ * caller that concatenated two reads of the counters, does. The counts are
150
+ * published and the scaled figure is withheld, because the scale is the part
151
+ * that is not true.
152
+ */
153
+ | "inconsistent";
154
+ export declare const CONVERSION_SILENCES: readonly ConversionSilence[];
155
+ /**
156
+ * One line per silence, for a surface saying why a page has no funnel figure.
157
+ *
158
+ * **The sentences are the order's own, moved here rather than written again.**
159
+ * Every member of this set is also a {@link ConversionStanding}, and
160
+ * {@link describeConversionStanding} has had a line for each since the order
161
+ * was built — so a second spelling of *no page views counted at the door* would
162
+ * be the thing this subsystem's census of silences exists to stop, one module
163
+ * in. The standing now defers to this for the seven it shares, which is why the
164
+ * text below is unchanged from what that function returned.
165
+ *
166
+ * The condition's own sentence — `describeSilenceCondition` in
167
+ * [`silences.ts`](silences.ts) — is the third and is not a replacement for
168
+ * either: it is the wording shared across every reading here, for a card
169
+ * speaking about two readings at once.
170
+ */
171
+ export declare const describeConversionSilence: (silence: ConversionSilence) => string;
172
+ /** Where one page stands in the order, or why it is not in it. */
173
+ export type ConversionStanding =
174
+ /** In the order, by the readers it loses between the two ends of its sharpest ask. */
175
+ "ranked"
176
+ /**
177
+ * Every reader who reached one of its asks went on to answer it.
178
+ *
179
+ * The cheerful answer, and a thin window produces it as well: two readers who
180
+ * both converted leak nobody either. The arrivals travel with the row, so the
181
+ * two are told apart on the row rather than by this word.
182
+ */
183
+ | "unleaked"
184
+ /**
185
+ * Nothing asks this version of the page for anything.
186
+ *
187
+ * **Not a silence**, which is the distinction worth keeping: no figure is
188
+ * being withheld, because no question was written. A deployment reading it is
189
+ * being told that the page has no funnel to measure rather than that its
190
+ * funnel could not be measured, and those are opposite instructions.
191
+ */
192
+ | "unasked" | ConversionSilence;
193
+ export declare const CONVERSION_STANDINGS: readonly ConversionStanding[];
194
+ /** One line per standing, for a surface naming why a page is where it is. */
195
+ export declare const describeConversionStanding: (standing: ConversionStanding) => string;
196
+ /** One revision of one page, as the order of conversions has it. */
197
+ export type LeakingPage = {
198
+ readonly treeId: TreeId;
199
+ readonly revision: number;
200
+ /**
201
+ * The audience this row is about, or `null` where the reading named none.
202
+ *
203
+ * Two forms of one page stand here as two rows, as they do in the order of
204
+ * falls (0250): both are live, both are asked the same question, and the two
205
+ * answers are of two populations. Nothing is summed across them.
206
+ */
207
+ readonly audienceId: AudienceId | null;
208
+ readonly standing: ConversionStanding;
209
+ /** Page views counted at the door, exact, or `null` where this revision has no row. */
210
+ readonly opened: number | null;
211
+ /** This page's own straddle rate, which is what scales its loss. */
212
+ readonly inflation: number | null;
213
+ /** How many questions this revision is asked, as the reading read them. */
214
+ readonly questions: number;
215
+ /** Of those, how many name a part this revision no longer has. */
216
+ readonly stalePairs: number;
217
+ /**
218
+ * The ask that loses the most readers between its two ends, carried whole and
219
+ * unchanged.
220
+ *
221
+ * `null` where no question of this revision could be ranked — which is every
222
+ * standing but `ranked`, `unleaked` and `inconsistent`.
223
+ */
224
+ readonly at: PairReach | null;
225
+ /** Readers lost between that ask's two ends, as the window's counters have it. */
226
+ readonly lost: number | null;
227
+ /**
228
+ * The same loss on the door's scale, which is the key the order is on, and
229
+ * the **most** that loss could be.
230
+ *
231
+ * Not a count of people and not rounded into one. Withheld where the page has
232
+ * no rankable question, or no row to scale one by.
233
+ *
234
+ * It is {@link PairLeak.atMost} carried through unchanged, so the figure this
235
+ * order ranks on and the figure the funnel answer publishes cannot come to
236
+ * disagree.
237
+ */
238
+ readonly readers: number | null;
239
+ /**
240
+ * The least that loss could be, given the straddle this page's own door
241
+ * measured.
242
+ *
243
+ * {@link PairLeak.atLeast}, carried through on the same terms as
244
+ * {@link LeakingPage.readers}: both or neither. It equals `readers` wherever
245
+ * nobody's visit spanned two windows, and falls away from it as a
246
+ * deployment's rollup window shortens relative to how long its readers stay.
247
+ *
248
+ * The figure to print where a page's measurement is under suspicion: a
249
+ * `counts-inflated` deployment (0336) has every conversion key withdrawn from
250
+ * its order, and this one number is the part of it a straddle cannot have
251
+ * manufactured.
252
+ */
253
+ readonly readersAtLeast: number | null;
254
+ /**
255
+ * Of the readers who reached that ask, the share that answered it, carried
256
+ * through from the pair unchanged.
257
+ *
258
+ * Sound without any correction, because both of its counts come off the same
259
+ * row — so it is published even for a page whose scaled figure is withheld as
260
+ * inconsistent.
261
+ */
262
+ readonly rate: number | null;
263
+ };
264
+ /** A deployment's pages, in the order their conversions should be looked at. */
265
+ export type DeploymentConversion = {
266
+ /**
267
+ * Every page with a leak and a scale for it, worst first.
268
+ *
269
+ * Most readers lost at the door's scale, then the worse rate, then by tree id
270
+ * and newest revision first — so two pages that leak the same do not reorder
271
+ * on a refresh.
272
+ */
273
+ readonly ranked: readonly LeakingPage[];
274
+ /** Every other page, by tree id and newest revision first. */
275
+ readonly unranked: readonly LeakingPage[];
276
+ /** The head of the order, which is the funnel to look at first. */
277
+ readonly worst: LeakingPage | null;
278
+ /**
279
+ * Whether the page named {@link DeploymentConversion.worst} is first however
280
+ * the straddle fell: its floor is at or above every other ranked page's
281
+ * ceiling.
282
+ *
283
+ * The order is on a ceiling, so two pages whose intervals overlap could be
284
+ * either way round and the order has to pick one. This says whether that pick
285
+ * was forced. `true` where nothing can overtake the head — including the
286
+ * order of one, where there is nothing to overtake it — `false` where the next
287
+ * page's ceiling reaches the head's floor, and `null` where no page is ranked
288
+ * at all.
289
+ *
290
+ * One comparison rather than a second order, and deliberately so: ranking on
291
+ * the floor instead would be a different key for the same question, and the key
292
+ * is the one the record that built this order named. What a surface does with a
293
+ * `false` is say so — *these two are too close to call at your rollup window* —
294
+ * which is a truer sentence than either order alone.
295
+ */
296
+ readonly worstSecure: boolean | null;
297
+ /** How many pages stand in each state, over the ranked and the unranked alike. */
298
+ readonly standings: Readonly<Record<ConversionStanding, number>>;
299
+ /**
300
+ * Distinct trees across every page read, which is not the number of pages.
301
+ *
302
+ * Two revisions of one tree are two live versions of one page and both stand
303
+ * in the order, as they do in the order of falls (0250).
304
+ */
305
+ readonly trees: number;
306
+ /**
307
+ * Page views counted at the door across the pages handed in, added.
308
+ *
309
+ * Exact and addable, for the reason no other figure here is: a page view
310
+ * began on one revision of one tree and was counted once (0219). It is a
311
+ * weight rather than a deployment total — this sees the pages its caller
312
+ * read, not the deployment's.
313
+ */
314
+ readonly arrivals: number;
315
+ /**
316
+ * Funnel questions across the pages handed in, added.
317
+ *
318
+ * A question belongs to one revision of one page in one form, so two pages'
319
+ * questions are two questions even where both name the same two ends: the
320
+ * same ask of two pages has two answers.
321
+ */
322
+ readonly questions: number;
323
+ /** Of those, how many name a part the revision asking them no longer has. */
324
+ readonly stalePairs: number;
325
+ /**
326
+ * Readings of a revision beyond the first, which were dropped.
327
+ *
328
+ * A caller that concatenated two reads holds one page twice, and a page twice
329
+ * in an order is the one way an order can lie about how much there is to fix
330
+ * (0158).
331
+ */
332
+ readonly duplicated: number;
333
+ };
334
+ /**
335
+ * A deployment's pages, in the order their funnels should be looked at.
336
+ *
337
+ * ```ts
338
+ * const assembly = windowAssemblyOf(window, context)
339
+ * const order = deploymentConversionOf(windowFunnelsOf(window, assembly).pages)
340
+ * ```
341
+ *
342
+ * Takes the funnel answers rather than the counters, for the reason every
343
+ * derived reading in this subsystem takes readings: each answer is separately
344
+ * useful and separately drawn, and deriving one twice is how two screens come
345
+ * to disagree about one page.
346
+ */
347
+ export declare const deploymentConversionOf: (funnels: readonly FunnelReach[]) => DeploymentConversion;
348
+ //# sourceMappingURL=conversion.d.ts.map