@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,327 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { audienceScopeRead, comparedAudiencesOf, crossesAudiences, } from "./audiences.js";
3
+ import { readingProgressOf } from "./progress.js";
4
+ export const CHANGE_SILENCES = everyMemberOf()([
5
+ "different-trees",
6
+ "different-audiences",
7
+ "audiences-mixed",
8
+ "nothing-measured",
9
+ ]);
10
+ /** One line per silence, for a surface putting the comparison in front of a person. */
11
+ export const describeChangeSilence = (silence) => {
12
+ switch (silence) {
13
+ case "different-trees":
14
+ return "the two readings are of different pages";
15
+ case "different-audiences":
16
+ return "the two readings are of different audiences, and so of different readers";
17
+ case "audiences-mixed":
18
+ return "one window holds two forms of the page and says which readers neither";
19
+ case "nothing-measured":
20
+ return "one of the two windows held no page views";
21
+ }
22
+ };
23
+ export const PAIR_FATES = everyMemberOf()([
24
+ "absent",
25
+ "moved",
26
+ "reordered",
27
+ "separated",
28
+ "unanchorable",
29
+ "unreached",
30
+ ]);
31
+ /** One line per fate, for a surface putting the comparison in front of a person. */
32
+ export const describePairFate = (fate) => {
33
+ switch (fate) {
34
+ case "absent":
35
+ return "one of the two parts is not in the other revision";
36
+ case "moved":
37
+ return "the two parts are no longer children of the same part";
38
+ case "reordered":
39
+ return "the two parts are now the other way round";
40
+ case "separated":
41
+ return "something now sits between the two parts";
42
+ case "unanchorable":
43
+ return "one of the two parts reported nothing that could anchor a stop";
44
+ case "unreached":
45
+ return "nobody reached the first of the two parts";
46
+ }
47
+ };
48
+ const NO_PARTS = Object.freeze({
49
+ shared: 0,
50
+ added: Object.freeze([]),
51
+ removed: Object.freeze([]),
52
+ moved: Object.freeze([]),
53
+ reworded: Object.freeze([]),
54
+ unreadable: 0,
55
+ });
56
+ const keyOf = (after, before) => `${after}\u0000${before}`;
57
+ const sideOf = (after, before) => {
58
+ const lost = Math.max(after.reached - before.reached, 0);
59
+ return {
60
+ reached: after.reached,
61
+ lost,
62
+ share: after.reached === 0 ? 0 : lost / after.reached,
63
+ };
64
+ };
65
+ /**
66
+ * Every pair of consecutive anchorable steps of every run, in reading order.
67
+ *
68
+ * Rebuilt from the steps rather than read off {@link ReadingProgress.stops},
69
+ * because a pair nobody stopped at is a measurement this module needs and a fall
70
+ * is the only thing progress keeps. A pair whose share went to zero is the best
71
+ * outcome a change can have, and reading only the falls would lose exactly that.
72
+ *
73
+ * One pass per run, carrying the previous anchorable step rather than searching
74
+ * backwards, which is how `progress.ts` stays linear and why the ledger is not
75
+ * quadratic any more.
76
+ */
77
+ const adjacenciesOf = (progress) => {
78
+ const pairs = [];
79
+ for (const run of progress.runs) {
80
+ let previous;
81
+ for (const step of run.steps) {
82
+ if (!step.anchors)
83
+ continue;
84
+ if (previous !== undefined) {
85
+ pairs.push({
86
+ after: previous.nodeId,
87
+ before: step.nodeId,
88
+ parentId: run.parentId,
89
+ side: sideOf(previous, step),
90
+ });
91
+ }
92
+ previous = step;
93
+ }
94
+ }
95
+ return pairs;
96
+ };
97
+ const placementsOf = (reading) => {
98
+ const byNode = new Map();
99
+ for (const part of reading.parts) {
100
+ byNode.set(part.nodeId, { parentId: part.parentId, anchors: part.standing !== "unknown" });
101
+ }
102
+ return byNode;
103
+ };
104
+ /**
105
+ * Why a pair of one reading is not a pair of the other, given that it is not.
106
+ *
107
+ * In order, because the answers are not exclusive and the first true one is the
108
+ * one worth saying: a part that is not there is not also moved, and a part that
109
+ * cannot anchor is not also separated. `separated` is therefore the narrow
110
+ * answer it should be — both parts there, both able to anchor, still children of
111
+ * one part, and no longer next to each other.
112
+ */
113
+ const fateOf = (pair, placements, pairs) => {
114
+ const after = placements.get(pair.after);
115
+ const before = placements.get(pair.before);
116
+ if (after === undefined || before === undefined)
117
+ return "absent";
118
+ if (!after.anchors || !before.anchors)
119
+ return "unanchorable";
120
+ if (after.parentId !== before.parentId)
121
+ return "moved";
122
+ if (pairs.has(keyOf(pair.before, pair.after)))
123
+ return "reordered";
124
+ return "separated";
125
+ };
126
+ /**
127
+ * Whether two shares are at least one reader's worth apart, in integers.
128
+ *
129
+ * `|w.lost ÷ w.reached − n.lost ÷ n.reached| ≥ 1 ÷ min(w.reached, n.reached)`,
130
+ * multiplied out by both denominators and the smaller of them so that no
131
+ * division happens: a float that lands a hair under the threshold would decide
132
+ * that a reader who exists does not. Exact while the counts stay inside
133
+ * `Number.MAX_SAFE_INTEGER` under a cube, which is about a hundred thousand
134
+ * views of one part of one revision in one window.
135
+ */
136
+ const beyondOneReaderIn = (was, now) => {
137
+ const difference = Math.abs(was.lost * now.reached - now.lost * was.reached);
138
+ return difference * Math.min(was.reached, now.reached) >= was.reached * now.reached;
139
+ };
140
+ const comparedStopOf = (pair, now) => {
141
+ const improvement = pair.side.share - now.share;
142
+ return {
143
+ after: pair.after,
144
+ before: pair.before,
145
+ parentId: pair.parentId,
146
+ was: pair.side,
147
+ now,
148
+ improvement,
149
+ resolution: 1 / Math.min(pair.side.reached, now.reached),
150
+ beyondOneReader: beyondOneReaderIn(pair.side, now),
151
+ readersKept: improvement * now.reached,
152
+ };
153
+ };
154
+ /**
155
+ * The side of an unreached pair that is worth reporting: the one that reached
156
+ * somebody, where exactly one did.
157
+ *
158
+ * Both sides are true of themselves, and only one of them has a fall on it. A
159
+ * pair nobody reached on either side is filed on the earlier reading, because
160
+ * that is the baseline the question is asked against.
161
+ */
162
+ const unreachedSideOf = (pair, now) => {
163
+ const reporting = pair.side.reached === 0 && now.reached > 0;
164
+ return {
165
+ after: pair.after,
166
+ before: pair.before,
167
+ parentId: pair.parentId,
168
+ side: reporting ? "now" : "was",
169
+ fate: "unreached",
170
+ reached: reporting ? now.reached : pair.side.reached,
171
+ share: reporting ? now.share : pair.side.share,
172
+ };
173
+ };
174
+ /**
175
+ * The better of two, which is the ranking rule spelled once.
176
+ *
177
+ * `>` rather than `>=` keeps the first in reading order when two stops kept the
178
+ * same readers, the same way `progress.ts` ranks the steepest fall.
179
+ */
180
+ const moreKeptOf = (standing, next) => standing === null || next.readersKept > standing.readersKept ? next : standing;
181
+ const moreLostOf = (standing, next) => standing === null || next.readersKept < standing.readersKept ? next : standing;
182
+ /** A part's own words, as one string, so two readings' words compare in one go. */
183
+ const wordsOf = (part) => part.copy.words.join("\u0000");
184
+ const partsChangedOf = (was, now) => {
185
+ const earlier = new Map();
186
+ for (const part of was.parts)
187
+ earlier.set(part.nodeId, part);
188
+ const added = [];
189
+ const removed = [];
190
+ const moved = [];
191
+ const reworded = [];
192
+ let shared = 0;
193
+ let unreadable = 0;
194
+ for (const part of now.parts) {
195
+ const before = earlier.get(part.nodeId);
196
+ if (before === undefined) {
197
+ added.push(part.nodeId);
198
+ continue;
199
+ }
200
+ shared += 1;
201
+ if (before.parentId !== part.parentId)
202
+ moved.push(part.nodeId);
203
+ if (wordsOf(before) !== wordsOf(part))
204
+ reworded.push(part.nodeId);
205
+ else if (before.copy.unread.length > 0 || part.copy.unread.length > 0)
206
+ unreadable += 1;
207
+ }
208
+ const later = new Set(now.parts.map((part) => part.nodeId));
209
+ for (const part of was.parts)
210
+ if (!later.has(part.nodeId))
211
+ removed.push(part.nodeId);
212
+ return { shared, added, removed, moved, reworded, unreadable };
213
+ };
214
+ /**
215
+ * What a change did to the reading of a page, from a reading of each side.
216
+ *
217
+ * Handed two `PageReading`s rather than two `ReadingProgress`es, for the reason
218
+ * `readingProgressOf` is handed a reading: one input per side cannot be a
219
+ * mismatched pair, and the parts census needs the parts a progress leaves out —
220
+ * a root, and a part whose parent has no other child. The two progresses it
221
+ * derives are returned, so nothing downstream computes them twice.
222
+ */
223
+ export const readingChangeOf = (was, now) => {
224
+ const progress = { was: readingProgressOf(was), now: readingProgressOf(now) };
225
+ const empty = {
226
+ treeId: was.treeId,
227
+ revisions: { was: was.revision, now: now.revision },
228
+ audiences: comparedAudiencesOf(was, now),
229
+ progress,
230
+ stops: [],
231
+ incomparable: [],
232
+ mostKept: null,
233
+ mostLost: null,
234
+ };
235
+ if (was.treeId !== now.treeId) {
236
+ return { ...empty, parts: NO_PARTS, silence: "different-trees" };
237
+ }
238
+ /**
239
+ * Two forms of one page are two trees under one tree id, so the census is
240
+ * withheld with the stops rather than left standing: *three bands moved* read
241
+ * across two forms is the audience's own deltas presented as the change.
242
+ */
243
+ if (crossesAudiences(was, now)) {
244
+ return { ...empty, parts: NO_PARTS, silence: "different-audiences" };
245
+ }
246
+ const parts = partsChangedOf(was, now);
247
+ /**
248
+ * A side read as neither population, which is checked **before** the view
249
+ * floor because it is the cause of it: a refused page reading publishes a
250
+ * floor of nought with full counters behind it, so the floor alone reports a
251
+ * window of two forms as a window nobody read (0301).
252
+ *
253
+ * It sits below `crossesAudiences` for reading order rather than for
254
+ * precedence — the two states are mutually exclusive, so swapping them
255
+ * changes nothing. Taken off the two sides' own published scope rather than
256
+ * recomputed, which is what `audienceScopeRead` is for: the same call the
257
+ * funnel comparison makes for the same state (0300).
258
+ */
259
+ if (audienceScopeRead(was).reading === "mixed" || audienceScopeRead(now).reading === "mixed") {
260
+ return { ...empty, parts, silence: "audiences-mixed" };
261
+ }
262
+ /**
263
+ * A side with no views has no share to compare against, and the parts census
264
+ * does not need one — so the tree half of the answer stands and the reader
265
+ * half says why it is missing.
266
+ */
267
+ if (was.views === 0 || now.views === 0) {
268
+ return { ...empty, parts, silence: "nothing-measured" };
269
+ }
270
+ const earlierPairs = adjacenciesOf(progress.was);
271
+ const laterPairs = new Map();
272
+ for (const pair of adjacenciesOf(progress.now))
273
+ laterPairs.set(keyOf(pair.after, pair.before), pair);
274
+ const laterKeys = new Set(laterPairs.keys());
275
+ const earlierKeys = new Set(earlierPairs.map((pair) => keyOf(pair.after, pair.before)));
276
+ const laterPlacements = placementsOf(now);
277
+ const stops = [];
278
+ const incomparable = [];
279
+ const matched = new Set();
280
+ let mostKept = null;
281
+ let mostLost = null;
282
+ for (const pair of earlierPairs) {
283
+ const key = keyOf(pair.after, pair.before);
284
+ const later = laterPairs.get(key);
285
+ if (later === undefined) {
286
+ incomparable.push({
287
+ after: pair.after,
288
+ before: pair.before,
289
+ parentId: pair.parentId,
290
+ side: "was",
291
+ fate: fateOf(pair, laterPlacements, laterKeys),
292
+ reached: pair.side.reached,
293
+ share: pair.side.share,
294
+ });
295
+ continue;
296
+ }
297
+ matched.add(key);
298
+ if (pair.side.reached === 0 || later.side.reached === 0) {
299
+ incomparable.push(unreachedSideOf(pair, later.side));
300
+ continue;
301
+ }
302
+ const stop = comparedStopOf(pair, later.side);
303
+ stops.push(stop);
304
+ if (!stop.beyondOneReader)
305
+ continue;
306
+ if (stop.readersKept > 0)
307
+ mostKept = moreKeptOf(mostKept, stop);
308
+ if (stop.readersKept < 0)
309
+ mostLost = moreLostOf(mostLost, stop);
310
+ }
311
+ const earlierPlacements = placementsOf(was);
312
+ for (const pair of adjacenciesOf(progress.now)) {
313
+ if (matched.has(keyOf(pair.after, pair.before)))
314
+ continue;
315
+ incomparable.push({
316
+ after: pair.after,
317
+ before: pair.before,
318
+ parentId: pair.parentId,
319
+ side: "now",
320
+ fate: fateOf(pair, earlierPlacements, earlierKeys),
321
+ reached: pair.side.reached,
322
+ share: pair.side.share,
323
+ });
324
+ }
325
+ return { ...empty, parts, stops, incomparable, mostKept, mostLost, silence: null };
326
+ };
327
+ //# sourceMappingURL=change.js.map
@@ -4,32 +4,41 @@ import type { ReaderSignalJournal, ReaderSignalStoreError, ReceivedBatch } from
4
4
  import { type FunnelPair } from "./rollup.js";
5
5
  import type { ReaderTallyStore } from "./tally.js";
6
6
  /**
7
- * The one operation that empties the buffer.
7
+ * The one operation that counts the buffer.
8
8
  *
9
9
  * `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
10
10
  * keep what the fold produced — and until this module existed nothing joined
11
11
  * the three, so a deployment with signals switched on accumulated the largest
12
12
  * table it owns and counted none of it.
13
13
  *
14
- * **Counting and forgetting are one call, and that is the design rather than a
15
- * convenience.** A rollup reports *what this window added* (0147), so a batch
16
- * counted twice is counted twice forever: there is no idempotence to fall back
17
- * on and no way to notice afterwards, because the wrong number looks exactly
18
- * like a busy afternoon. The only defence that does not need durable bookkeeping
19
- * is for the set of batches rolled up and the set forgotten to be the same set,
20
- * decided once, in one place. That is this file, and it is why there is no
21
- * exported `applyReaderSignalRetention` beside it — a function that can forget
22
- * without counting is the data-loss bug, and one that can count without
23
- * forgetting is the double-count bug.
14
+ * **Counting and recording that it happened are one call, and that is the
15
+ * design rather than a convenience.** A rollup reports *what this window
16
+ * added* (0147), so a batch counted twice is counted twice forever: there is no
17
+ * idempotence to fall back on and no way to notice afterwards, because the
18
+ * wrong number looks exactly like a busy afternoon. The only defence that does
19
+ * not need durable bookkeeping is for the set of batches rolled up and the set
20
+ * marked as counted to be the same set, decided once, in one place. That is
21
+ * this file.
22
+ *
23
+ * **Until 5 November the mark was a delete** (0146), and the sentence above
24
+ * said *forgotten* where it now says *marked*. A delivery is now kept for the
25
+ * window its deployment states — thirty days by default, so that an operator
26
+ * can look at individual deliveries rather than only at counters (0349) — and
27
+ * deleted by a second sweep in `expire.ts`. What did not change is the thing
28
+ * the invariant protects: this run decides one prefix, counts it, and records
29
+ * that it counted it, and no other operation may touch that decision. What that
30
+ * split buys is that the two failures are no longer the same failure. A sweep
31
+ * that deletes without counting loses deliveries; this cannot delete at all.
24
32
  *
25
33
  * Nothing schedules it, for the reason nothing schedules telemetry's retention
26
- * or `auditSnapshot`: when a deployment forgets is an operational choice, and a
27
- * framework that quietly deleted a host's data on a timer it chose would be
28
- * making it. A host calls this from a cron route, a deploy hook, or by hand.
34
+ * or `auditSnapshot`: when a deployment counts is an operational choice, and a
35
+ * framework that quietly swept a host's data on a timer it chose would be
36
+ * making it. A host calls this from a cron route, a deploy hook, or by hand,
37
+ * and calls {@link expireReaderEvents} from the same place.
29
38
  *
30
39
  * **One run at a time, and the caller is what makes that true.** Two runs over
31
40
  * the same ripe prefix both roll it up and both apply; applying is additive
32
- * (0147), so the counters double and the buffer empties once, leaving nothing
41
+ * (0147), so the counters double and the prefix is marked once, leaving nothing
33
42
  * behind that could say what happened. Nothing here can prevent it — a journal
34
43
  * and a store are two handles with no shared transaction between them — so
35
44
  * serialising belongs to whatever schedules this. `apps/loom/scripts/
@@ -37,19 +46,34 @@ import type { ReaderTallyStore } from "./tally.js";
37
46
  * cheapest thing that works for a cron that overruns its own interval.
38
47
  */
39
48
  /**
40
- * The window is the age a batch reaches before it is counted and dropped, and
41
- * it is two arguments pulling opposite ways.
49
+ * The window is the age a batch reaches before it is counted, and it is two
50
+ * arguments pulling opposite ways.
42
51
  *
43
52
  * **Longer is more accurate.** `views` and `reached` count distinct page views,
44
53
  * distinctness does not add up, and a page view whose batches straddle two
45
54
  * windows is counted in both — the over-count 0147 accepts. `tally.ts` already
46
55
  * states the remedy in its own words: *a deployment that wants the bound small
47
56
  * makes the rollup window long relative to a page view.* This is that number.
57
+ * A deployment no longer has to guess whether it chose well: each run adds its
58
+ * window's page views to the counter the door counts arrivals into, so the
59
+ * difference between the two is what this setting actually cost
60
+ * (`page-views.ts`).
61
+ *
62
+ * **A run also writes down that it happened.** Applying a window stamps the
63
+ * fold's own timestamp on each revision's door row, which is what lets a
64
+ * deployment be told that nothing has folded for longer than its own schedule
65
+ * allows — the openings waiting are otherwise indistinguishable from the
66
+ * ordinary one-window lag this setting creates (0274).
48
67
  *
49
- * **Shorter is more anonymous.** The raw window is the entire mechanism by
50
- * which a view key stops existing (0146). The key is opaque, random and
51
- * correlates nothing outside the buffer, but it correlates that, and the
52
- * argument for it rests on how briefly it lives.
68
+ * **Shorter is more anonymous — and since 5 November this is no longer the
69
+ * window that governs that.** The view key stops existing when the row holding
70
+ * it is deleted, and that is now the kept window rather than this one
71
+ * (0349, 0351): a delivery is counted at this age and deleted at the age
72
+ * `expire.ts` is given. This setting still decides how much over-count a
73
+ * straddling page view causes, which is the accuracy argument above; what it no
74
+ * longer decides is how long a page view's signals stay correlatable. That
75
+ * number is `DEFAULT_READER_EVENT_RETENTION_MS` and the tension in it is
76
+ * recorded rather than hidden.
53
77
  *
54
78
  * An hour is long against a page view and short against a day, which is why it
55
79
  * is the default rather than a constant: rule 5 of `docs/signals.md` makes the
@@ -85,6 +109,19 @@ export type ReaderSignalWindow = z.infer<typeof readerSignalWindowSchema>;
85
109
  */
86
110
  export declare const DEFAULT_COLLECTION_SCAN = 5000;
87
111
  export declare const MAX_COLLECTION_SCAN = 50000;
112
+ /**
113
+ * A pair as a deployment asks it: the question, where it is asked, and the
114
+ * instant it began being asked.
115
+ *
116
+ * `countedFrom` is epoch milliseconds and is the whole of 0418's second half:
117
+ * a run whose window **begins** before that instant does not ask the question
118
+ * at all, and says so in its outcome. Absent means no start — the shape every
119
+ * pair had before, and the right one for a question a deployment has always
120
+ * asked.
121
+ */
122
+ export type AskedFunnelPair = FunnelPair & {
123
+ readonly countedFrom?: number;
124
+ };
88
125
  export type CollectionRequest = {
89
126
  readonly windowMs?: number;
90
127
  /**
@@ -95,8 +132,13 @@ export type CollectionRequest = {
95
132
  * already folded, because the batches those answers came from are gone. That
96
133
  * is the price of aggregates being the durable artefact and it is worth
97
134
  * knowing before a deployment waits a day for a number it will not get.
135
+ *
136
+ * **A pair carrying `countedFrom` is held back until a whole window is after
137
+ * it** (0418), rather than counted over whatever the first run happens to
138
+ * reach: a figure a screen labels *counting since Tuesday* must not hold
139
+ * readers from Monday.
98
140
  */
99
- readonly pairs?: readonly FunnelPair[];
141
+ readonly pairs?: readonly AskedFunnelPair[];
100
142
  readonly clock?: Clock;
101
143
  readonly scanLimit?: number;
102
144
  };
@@ -118,12 +160,63 @@ export type CollectionPlan = {
118
160
  readonly waiting: number;
119
161
  };
120
162
  export declare const collectionPlanOf: (scanned: readonly ReceivedBatch[], horizon: string) => CollectionPlan;
163
+ /** What a run may ask, and how many questions it held back (0418). */
164
+ export type FunnelsAsked = {
165
+ readonly asking: readonly FunnelPair[];
166
+ readonly withheld: number;
167
+ };
168
+ /**
169
+ * The pairs a run folding a window that **begins** at `from` may ask, and the
170
+ * count of the ones it may not.
171
+ *
172
+ * The comparison is against the oldest delivery in the window rather than
173
+ * against the run's own clock, and that is the whole of the rule: every
174
+ * delivery this run folds arrived at or after `from`, so a question whose start
175
+ * is at or before `from` is answered over readers who all arrived after it was
176
+ * asked. A question asked in the middle of a window is held back one run, which
177
+ * costs one window of an answer and buys a figure that means what its label
178
+ * says.
179
+ *
180
+ * **An unreadable instant withholds every question with a start**, because the
181
+ * fallback is the one that cannot be noticed: counting a step from a window
182
+ * nobody can place is a figure nobody can date.
183
+ */
184
+ export declare const funnelsAskedOf: (pairs: readonly AskedFunnelPair[], from: string) => FunnelsAsked;
121
185
  export declare const horizonOf: (configured: ReaderSignalWindow, now: string) => string | null;
122
186
  /** The half of the outcome a caller shows or logs, with nothing in it about a reader. */
123
187
  export type CollectionSummary = {
124
188
  readonly counted: number;
125
189
  readonly tallies: number;
126
190
  readonly funnels: number;
191
+ /**
192
+ * Funnel pairs this run was handed and did not ask, because the window it
193
+ * folded begins before the pair was first asked (0418).
194
+ *
195
+ * In the run's outcome rather than anywhere durable, for `redelivered`'s
196
+ * reason: a fold's own figures are not the artefact. Non-zero is the ordinary
197
+ * answer on the run after a step is set and a sign of something to look at
198
+ * if it stays non-zero — a deployment permanently behind on collection never
199
+ * reaches a window that starts after its newest question.
200
+ */
201
+ readonly withheldFunnels: number;
202
+ /**
203
+ * Hourly rows this run wrote for what readers did (`acted.ts`).
204
+ *
205
+ * A slice of the tallies rather than a figure beside them: a window in which
206
+ * nobody pressed, opened or sent anything writes none, however many tallies
207
+ * it wrote, because the counter holds what readers *did* and a page being on
208
+ * screen is not one of those.
209
+ */
210
+ readonly acted: number;
211
+ /**
212
+ * Hourly rows this run wrote for the funnels it was asked (`funnel-hours.ts`).
213
+ *
214
+ * A cut of the answers rather than a figure beside them: a window in which
215
+ * nobody reached a pair's first end writes none, however many answers it
216
+ * wrote, because an answer is written at nought for a question a deployment
217
+ * asked and an hour is written only where somebody entered the funnel.
218
+ */
219
+ readonly funnelHours: number;
127
220
  /** Distinct page views the window held. */
128
221
  readonly views: number;
129
222
  /**
@@ -132,12 +225,52 @@ export type CollectionSummary = {
132
225
  * failure mode here, so the number travels with the run that produced it.
133
226
  */
134
227
  readonly uncorrelated: number;
228
+ /**
229
+ * Of the batches counted, how many were a repeat of one already folded in
230
+ * this window and were therefore folded once (`rollup.ts`).
231
+ *
232
+ * A subset of `counted` rather than a number beside it: every one of them was
233
+ * read from the buffer and is forgotten with the rest. Non-zero every run is
234
+ * a sender retrying deliveries it already made, which is worth finding — and
235
+ * the figure is in the run's outcome rather than in a stored row because a
236
+ * fold's own numbers are not durable, only the counters it produced are.
237
+ */
238
+ readonly redelivered: number;
239
+ /**
240
+ * How old the oldest **uncounted** delivery the scan found was, in
241
+ * milliseconds, at the instant this run was taken.
242
+ *
243
+ * A fact about the buffer and about no reader, like every other figure here.
244
+ * It is free: a scan runs from the oldest uncounted end, so the first batch
245
+ * it read is the oldest one waiting, and this is one subtraction over it.
246
+ *
247
+ * **The run does the subtraction rather than the caller**, because the
248
+ * caller's clock is not this run's: a surface that read the age against its
249
+ * own `now` would publish a number nothing had measured.
250
+ *
251
+ * **It is the fold's lag, not the kept window** (0351). It was both while a
252
+ * counted delivery was deleted in the same breath, which is why
253
+ * `retentionPromiseOf` used to be handed this outcome; the ceiling readers
254
+ * are promised is now about deletion, so that reading is handed the expiry
255
+ * run's own figure and this one answers the question it still owns — how far
256
+ * behind collection is.
257
+ *
258
+ * Never absent and always at least the ripeness window: a summary exists only
259
+ * where something was ripe.
260
+ */
261
+ readonly oldestMs: number;
135
262
  };
136
263
  export type CollectionOutcome = {
137
264
  readonly outcome: "collected";
138
265
  readonly summary: CollectionSummary;
139
- /** Rows the buffer removed. Below `counted` only if something else pruned first. */
140
- readonly removed: number;
266
+ /**
267
+ * Rows this run marked as counted.
268
+ *
269
+ * Below `counted` only where something had already marked them — which on
270
+ * one run at a time is nothing, and is why a figure below the count is
271
+ * worth seeing rather than a rounding difference.
272
+ */
273
+ readonly recorded: number;
141
274
  /** The scan filled its limit with ripe batches, so another run has work now. */
142
275
  readonly more: boolean;
143
276
  }
@@ -147,35 +280,37 @@ export type CollectionOutcome = {
147
280
  readonly waiting: number;
148
281
  }
149
282
  /**
150
- * The counters took the window and the buffer would not drop it.
283
+ * The counters took the window and the journal would not record it.
151
284
  *
152
285
  * Its own outcome because it is the one state that gets worse if it is
153
- * ignored: the batches are durable in the counters and still in the buffer,
154
- * so the next run counts them again. An operator seeing this prunes below the
155
- * reported position by hand, or fixes the buffer before the next run.
286
+ * ignored: the batches are durable in the counters and still unmarked, so the
287
+ * next run counts them again. An operator seeing this marks the prefix by
288
+ * hand, or fixes the store before the next run — and must not reach for a
289
+ * delete, which would lose the deliveries and leave the double-count.
156
290
  */
157
291
  | {
158
- readonly outcome: "counted-not-forgotten";
292
+ readonly outcome: "counted-not-recorded";
159
293
  readonly summary: CollectionSummary;
160
294
  readonly before: number;
161
295
  readonly error: ReaderSignalStoreError;
162
296
  }
163
- /** The window was not usable. Nothing was read, counted or deleted. */
297
+ /** The window was not usable. Nothing was read, counted or marked. */
164
298
  | {
165
299
  readonly outcome: "refused";
166
300
  readonly reason: string;
167
301
  }
168
- /** Read or write failed before anything became durable. Nothing was deleted. */
302
+ /** Read or write failed before anything became durable. Nothing was marked. */
169
303
  | {
170
304
  readonly outcome: "unavailable";
171
305
  readonly error: ReaderSignalStoreError;
172
306
  };
173
307
  /**
174
- * Count a window of the buffer into the durable counters, then drop it.
308
+ * Count a window of the buffer into the durable counters, then record that it
309
+ * was counted.
175
310
  *
176
311
  * The order is the safe one and the reverse is a data-loss bug that looks like
177
- * a feature working: aggregates first, the buffer second. What that leaves is
178
- * `counted-not-forgotten`, which is visible and recoverable — the opposite
312
+ * a feature working: aggregates first, the mark second. What that leaves is
313
+ * `counted-not-recorded`, which is visible and recoverable — the opposite
179
314
  * order's failure is neither.
180
315
  */
181
316
  export declare const collectReaderSignals: (journal: ReaderSignalJournal, store: ReaderTallyStore, request?: CollectionRequest) => Promise<CollectionOutcome>;