@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,212 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { NodeId, TreeId } from "../ids.js";
3
+ import type { PrimitiveRole } from "../role.js";
4
+ import type { PrimitiveType } from "../primitive-type.js";
5
+ import type { PageReading, PartStanding } from "./parts.js";
6
+ /**
7
+ * Where in a page reading stops.
8
+ *
9
+ * [`parts.ts`](parts.ts) answers *which* parts were read, part by part, and
10
+ * notes in passing that the shape of that answer is where the reading stops —
11
+ * which a set of rows keyed by id cannot show. This is that shape, taken off the
12
+ * same reading and nothing else: no payload, no browser change, no counter that
13
+ * does not already exist, and no byte on any wire. It is the second thing
14
+ * derived from the join rather than the first thing asked of a reader.
15
+ *
16
+ * The question it answers is *readers get through the first four bands and the
17
+ * fifth is where they leave*, and it is the first thing in this subsystem that
18
+ * tells a model something to act on rather than telling a person something true.
19
+ *
20
+ * ## A stop is between siblings, never between a page and a number
21
+ *
22
+ * The unit is a **run**: one parent's element children, in the order a reader
23
+ * meets them. Every comparison this module makes is between two members of one
24
+ * run, and that is the whole of why its figures can be trusted:
25
+ *
26
+ * - **A ratio of two `reached` counts is sound where either count alone is
27
+ * not.** `reached` is a distinct view count summed across rollup windows, so
28
+ * it is generous by every page view that straddled a boundary
29
+ * ([0147](../../decisions/0147-a-rollup-is-added-to-what-is-stored-and-a-distinct-view-count-is-therefore-approximate.md),
30
+ * measured since
31
+ * [0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)).
32
+ * Two parts of one page are inflated by the same straddling readers, because
33
+ * a reader who straddled a window straddled it for the whole page — so the
34
+ * inflation is very nearly common to the numerator and the denominator and
35
+ * divides out. *Four in ten readers stopped here* survives an over-count that
36
+ * *four hundred readers* does not.
37
+ * - **Siblings are comparable and cousins are not.** A part deep inside the
38
+ * first band comes before the second band in reading order and is reached by
39
+ * fewer readers than either, so a page-wide sequence of `reached` is not
40
+ * descending and a fall in it is not a stop. Within a run, every step is one
41
+ * level of one parent, and a fall from one to the next is a reader who got to
42
+ * one and not the other.
43
+ *
44
+ * ## What cannot anchor a stop
45
+ *
46
+ * A part whose standing is `unknown` **while the window held views** reported
47
+ * something other than coming into view — a press was delegated to a band no
48
+ * `viewed` ever named, so a reader plainly had it in front of them and the
49
+ * counter that would say so is missing (0167 does not put `viewed` on a
50
+ * delegated signal's ancestry). Its `reached` is 0 and the truth is *not zero,
51
+ * unknown*. Treating it as the end of a run would report a cliff that nobody
52
+ * fell off, which is the lie in the direction nobody checks. So it is passed
53
+ * over: a stop names the two nearest parts in the run that can anchor one, and
54
+ * the parts passed over are counted where a reading can see them.
55
+ *
56
+ * Pure, linear in the parts, and reaches no store, clock or DOM — it adds
57
+ * nothing to the broadcaster's import graph.
58
+ */
59
+ /** One part as a point on its parent's sequence. */
60
+ export type ReadingStep = {
61
+ readonly nodeId: NodeId;
62
+ readonly type: PrimitiveType;
63
+ /** What part it plays (0114), or `null` where its type declared none. */
64
+ readonly role: PrimitiveRole | null;
65
+ readonly standing: PartStanding;
66
+ /**
67
+ * Distinct page views that reported it coming into view, and `0` where no row
68
+ * named it at all.
69
+ *
70
+ * Zero means two different things and {@link ReadingStep.anchors} is which:
71
+ * nobody got here, or nothing can say.
72
+ */
73
+ readonly reached: number;
74
+ /**
75
+ * Whether this step can be either end of a stop.
76
+ *
77
+ * False for a part that reported something other than a view, whose `reached`
78
+ * of 0 is an absence of evidence rather than an absence of readers.
79
+ */
80
+ readonly anchors: boolean;
81
+ };
82
+ /**
83
+ * Two parts of one run, and the readers who reached the first and not the
84
+ * second.
85
+ *
86
+ * Only ever a fall. A rise is {@link ReadingRun.gained}, because a reader who
87
+ * scrolls cannot produce one and the reason they exist is worth a different
88
+ * sentence.
89
+ */
90
+ export type ReadingStop = {
91
+ /** The part they reached. */
92
+ readonly after: NodeId;
93
+ /** The next part in the run that could anchor a stop, which fewer reached. */
94
+ readonly before: NodeId;
95
+ /** Views that reached `after`, which is the denominator of `share`. */
96
+ readonly reached: number;
97
+ /** Views that reached `after` and not `before`. */
98
+ readonly lost: number;
99
+ /**
100
+ * `lost ÷ reached`, in `(0, 1]`.
101
+ *
102
+ * Both numbers are `reached` counts off the same rows, so this is the figure
103
+ * that survives the over-count the counts themselves carry. It is never
104
+ * divided by the page's views or by the page views counted at the door — those
105
+ * are a different measurement of a different thing, and dividing across the
106
+ * two would put a number on a screen that no two rows agree about.
107
+ */
108
+ readonly share: number;
109
+ };
110
+ /** One parent's children, in the order a reader meets them. */
111
+ export type ReadingRun = {
112
+ readonly parentId: NodeId;
113
+ /** The depth of the steps, which is one below the parent's. */
114
+ readonly depth: number;
115
+ readonly steps: readonly ReadingStep[];
116
+ /** Every fall, in run order. */
117
+ readonly stops: readonly ReadingStop[];
118
+ /**
119
+ * The last step in run order that any view reached, or `null` where none did.
120
+ *
121
+ * *How far down they got*, as a node rather than a fraction.
122
+ */
123
+ readonly furthest: NodeId | null;
124
+ /**
125
+ * Pairs where more views reached the later part than the earlier one.
126
+ *
127
+ * Scrolling cannot do this, so it is a reader who arrived somewhere other than
128
+ * the top — an anchored link, a restored scroll position — or a part that is
129
+ * on screen whatever the reader does, such as a footer a short page never
130
+ * pushes down. Worth seeing and not worth reporting as a negative stop.
131
+ */
132
+ readonly gained: number;
133
+ };
134
+ export type ReadingProgress = {
135
+ readonly treeId: TreeId;
136
+ readonly revision: number;
137
+ /**
138
+ * The audience the reading was of, carried through unchanged.
139
+ *
140
+ * Carried rather than derived, and carried for one reason: an order over a
141
+ * deployment's pages picks each page's door row by this trio and refuses to
142
+ * count a page twice by it (`readingKeyOf`), and a progress reading that
143
+ * dropped the audience would hand that order two forms of one page it could
144
+ * not tell apart.
145
+ */
146
+ readonly audienceId: AudienceId | null;
147
+ /**
148
+ * Every audience the window named, carried through unchanged.
149
+ *
150
+ * Carried for the reason {@link ReadingProgress.audienceId} is, one step
151
+ * further on: the pair of fields is what `audienceScopeRead` needs, and
152
+ * without the census every reading downstream of this one gets `one` where
153
+ * the window was two forms read as neither (0300). More than one member with
154
+ * {@link ReadingProgress.audienceId} `null` is that refusal, and what it
155
+ * costs to drop is written on {@link ReadingProgress.views}.
156
+ */
157
+ readonly audiences: readonly AudienceId[];
158
+ /**
159
+ * The page's view floor, carried through from the reading unchanged.
160
+ *
161
+ * Zero means nothing stopped anywhere, so `runs` is empty rather than a page
162
+ * of parts that all look skipped.
163
+ *
164
+ * **It does not mean nothing was measured, and that is the second job it was
165
+ * doing.** A window holding two forms of the page with none asked for is read
166
+ * as neither, so every part is `unknown` and this is nought while the
167
+ * counters behind it are full and the door beside it has arrivals in it, which
168
+ * is the page reading's refusal held against the door's sum (0290, 0299). The
169
+ * two states are told apart by the census above and nowhere else, which is
170
+ * why it travels.
171
+ */
172
+ readonly views: number;
173
+ /**
174
+ * Every run of two or more children, in reading order.
175
+ *
176
+ * A run of one is left out: a stop is between two parts, and an only child has
177
+ * nowhere for reading to stop. Every part of the page is a step in at most one
178
+ * run — its parent's — so no reader's progress is counted at two depths.
179
+ */
180
+ readonly runs: readonly ReadingRun[];
181
+ /**
182
+ * The sharpest fall on the page: most views lost, then largest share, then
183
+ * first in reading order.
184
+ *
185
+ * By views lost rather than by share, because *where does this page lose
186
+ * readers* is a question about readers. A band two readers out of three
187
+ * abandoned is a worse rate and a smaller problem than one four hundred out of
188
+ * a thousand did, and ranking by share would put the former at the top of
189
+ * every screen for ever.
190
+ */
191
+ readonly steepest: ReadingStop | null;
192
+ /**
193
+ * Parts that could not anchor a stop, because they reported something other
194
+ * than coming into view.
195
+ *
196
+ * Empty on an ordinary page. A long list is a diagnosis: presses are being
197
+ * delegated to regions that no `viewed` names, which is a sender or a
198
+ * primitive not reporting what it is, rather than a page nobody read.
199
+ */
200
+ readonly unanchored: readonly NodeId[];
201
+ /** Every run's {@link ReadingRun.gained}, added. */
202
+ readonly gained: number;
203
+ };
204
+ /**
205
+ * Where reading stops, from a reading of one revision.
206
+ *
207
+ * Handed the output of `pageReadingOf`, because the standings and the reading
208
+ * order are what this is made of and deriving them twice is how two screens
209
+ * come to disagree. A caller with counters and a tree reads the parts first.
210
+ */
211
+ export declare const readingProgressOf: (reading: PageReading) => ReadingProgress;
212
+ //# sourceMappingURL=progress.d.ts.map
@@ -0,0 +1,150 @@
1
+ const stepOf = (part) => ({
2
+ nodeId: part.nodeId,
3
+ type: part.type,
4
+ role: part.role,
5
+ standing: part.standing,
6
+ reached: part.counters?.reached ?? 0,
7
+ /**
8
+ * `read` carries a reach above zero and `skipped` carries no row at all, and
9
+ * both are statements. `unknown` is the absence of one — and with views on the
10
+ * page it is the sharp case this module refuses to build a cliff out of.
11
+ */
12
+ anchors: part.standing !== "unknown",
13
+ });
14
+ /**
15
+ * The falls and the rises of one run, over the steps that can anchor either.
16
+ *
17
+ * One pass. The previous anchorable step is carried rather than searched for
18
+ * backwards, so a run of unanchorable parts costs its length and not its square
19
+ * — the ledger was quadratic once and a 6,000-node page took 314 ms.
20
+ */
21
+ const pairsOf = (steps) => {
22
+ const stops = [];
23
+ let gained = 0;
24
+ let previous;
25
+ for (const step of steps) {
26
+ if (!step.anchors)
27
+ continue;
28
+ if (previous !== undefined) {
29
+ const lost = previous.reached - step.reached;
30
+ if (lost > 0) {
31
+ stops.push({
32
+ after: previous.nodeId,
33
+ before: step.nodeId,
34
+ reached: previous.reached,
35
+ lost,
36
+ share: lost / previous.reached,
37
+ });
38
+ }
39
+ else if (lost < 0)
40
+ gained += 1;
41
+ }
42
+ previous = step;
43
+ }
44
+ return { stops, gained };
45
+ };
46
+ /** The last step any view reached, which is a scan from the end rather than a sort. */
47
+ const furthestOf = (steps) => {
48
+ for (let at = steps.length - 1; at >= 0; at -= 1) {
49
+ const step = steps[at];
50
+ if (step !== undefined && step.reached > 0)
51
+ return step.nodeId;
52
+ }
53
+ return null;
54
+ };
55
+ const runOf = (parentId, parts) => {
56
+ const steps = parts.map(stepOf);
57
+ const { stops, gained } = pairsOf(steps);
58
+ return {
59
+ parentId,
60
+ depth: parts[0]?.depth ?? 0,
61
+ steps,
62
+ stops,
63
+ furthest: furthestOf(steps),
64
+ gained,
65
+ };
66
+ };
67
+ /**
68
+ * The steepest of two, which is the ranking rule spelled once.
69
+ *
70
+ * `>` rather than `>=` on both keys is what makes the third rule — first in
71
+ * reading order — hold without a third comparison: an equal candidate never
72
+ * displaces the one already standing, and the parts arrive in reading order.
73
+ */
74
+ const steeperOf = (standing, next) => {
75
+ if (standing === null)
76
+ return next;
77
+ if (next.lost > standing.lost)
78
+ return next;
79
+ if (next.lost === standing.lost && next.share > standing.share)
80
+ return next;
81
+ return standing;
82
+ };
83
+ /**
84
+ * Where reading stops, from a reading of one revision.
85
+ *
86
+ * Handed the output of `pageReadingOf`, because the standings and the reading
87
+ * order are what this is made of and deriving them twice is how two screens
88
+ * come to disagree. A caller with counters and a tree reads the parts first.
89
+ */
90
+ export const readingProgressOf = (reading) => {
91
+ const empty = {
92
+ treeId: reading.treeId,
93
+ revision: reading.revision,
94
+ audienceId: reading.audienceId,
95
+ audiences: reading.audiences,
96
+ views: reading.views,
97
+ };
98
+ /**
99
+ * A window with no views of this revision answers nothing, rather than
100
+ * answering that every part was abandoned.
101
+ *
102
+ * Every standing is `unknown` below that floor (`parts.ts`), so there is not
103
+ * an anchorable step on the page and every run would be a list of parts with
104
+ * no stop in it. Saying so once here is cheaper to read than a page of empty
105
+ * runs, and it is the same refusal `unknown` already makes one level down.
106
+ *
107
+ * **A reading refused for holding two forms arrives here as the same nought**
108
+ * and is answered the same way, which is right: there is no stop to publish
109
+ * either way. What is not right is a reading further on calling it *a page
110
+ * nobody read*, and the census this carries is what lets it say which of the
111
+ * two it was holding (0301).
112
+ */
113
+ if (reading.views === 0) {
114
+ return { ...empty, runs: [], steepest: null, unanchored: [], gained: 0 };
115
+ }
116
+ /**
117
+ * Grouped by parent in one pass. The parts arrive in reading order, so each
118
+ * group is in run order by construction and nothing is sorted.
119
+ */
120
+ const byParent = new Map();
121
+ for (const part of reading.parts) {
122
+ if (part.parentId === null)
123
+ continue;
124
+ const siblings = byParent.get(part.parentId);
125
+ if (siblings === undefined)
126
+ byParent.set(part.parentId, [part]);
127
+ else
128
+ siblings.push(part);
129
+ }
130
+ const runs = [];
131
+ let steepest = null;
132
+ let gained = 0;
133
+ for (const [parentId, siblings] of byParent) {
134
+ if (siblings.length < 2)
135
+ continue;
136
+ const run = runOf(parentId, siblings);
137
+ runs.push(run);
138
+ gained += run.gained;
139
+ for (const stop of run.stops)
140
+ steepest = steeperOf(steepest, stop);
141
+ }
142
+ return {
143
+ ...empty,
144
+ runs,
145
+ steepest,
146
+ unanchored: reading.parts.filter((part) => part.standing === "unknown").map((part) => part.nodeId),
147
+ gained,
148
+ };
149
+ };
150
+ //# sourceMappingURL=progress.js.map
@@ -0,0 +1,108 @@
1
+ /**
2
+ * A quotient of one window's figure against the other's, and the reason there
3
+ * is not one.
4
+ *
5
+ * Three comparisons of two windows publish ratios: what a change did to the
6
+ * share of readers who acted inside a part
7
+ * ([`action-change.ts`](action-change.ts)), to whether readers had time for the
8
+ * words in front of them ([`pace-change.ts`](pace-change.ts)), and to the rate
9
+ * at which a funnel converts ([`funnel-change.ts`](funnel-change.ts)). Until
10
+ * this module each of them spelled the rule itself, in three copies that
11
+ * agreed — and two spellings of one rule that agree today is the fault this
12
+ * subsystem has been bitten by twice (0218, 0235). A fourth comparison written
13
+ * after them would have picked whichever copy it read last.
14
+ *
15
+ * ## The two states the one `null` was
16
+ *
17
+ * Every copy was this:
18
+ *
19
+ * ```ts
20
+ * was === undefined || now === undefined || was === 0 ? null : now / was
21
+ * ```
22
+ *
23
+ * and its `null` meant two things a caller could not tell apart. **Neither
24
+ * side measured this** — a leaf, a part with no row, a part nobody reached, a
25
+ * passage with no words — against **the earlier side measured nought**, which
26
+ * is a measurement and the state a rise from nothing is read off. *Nobody acted
27
+ * here and now four in ten do* and *nothing here can be compared* arrived as
28
+ * one value, on six published fields.
29
+ *
30
+ * So the figure a comparison publishes is this pair rather than a bare number:
31
+ * {@link Ratio.ratio} where there is a quotient, and {@link Ratio.absent}
32
+ * naming which state it is in where there is not. Exactly one of the two is
33
+ * ever non-null.
34
+ *
35
+ * ## Why the reason is published rather than left to be derived
36
+ *
37
+ * A surface holds both sides of every comparison, so it could in principle
38
+ * work the reason out for itself. It would have to know, per field, which pair
39
+ * of figures the quotient was taken over and what each side withholds and why
40
+ * — `usesPerReader` is withheld at a *measured* nought on purpose (0242), so
41
+ * the obvious derivation gets that field backwards. That knowledge is the
42
+ * reading's, the reading has it in hand at the division, and a rule derived a
43
+ * second time somewhere else is the fault above with a longer fuse.
44
+ *
45
+ * Pure, allocation-per-call and nothing else: no store, no clock, no DOM, and
46
+ * no import that reaches a package, so a comparison that imports it stays
47
+ * outside the broadcaster's import graph.
48
+ */
49
+ /** Why there is no quotient. */
50
+ export type RatioAbsence =
51
+ /**
52
+ * One of the two windows did not measure this, so there is nothing to divide.
53
+ *
54
+ * The absence is the other side's as much as this one's: a part that was a
55
+ * leaf and now bears an inside has a share now and never had one, and a
56
+ * window with no page views has no figure of any kind. What each side
57
+ * withholds and why is that reading's own rule, and this says only that one
58
+ * of them did.
59
+ */
60
+ "unmeasured"
61
+ /**
62
+ * Both windows measured it and the earlier one measured nought.
63
+ *
64
+ * A division by nought and not an absence of measurement, so the pair of
65
+ * sides a comparison publishes beside this is worth reading: the later side
66
+ * says whether the figure rose from nothing or stayed there, and the
67
+ * movement of the two standings says it in words. *Nobody acted in this band
68
+ * and four in ten do now* is this member with a later side above nought, and
69
+ * it is the state a surface most wants to draw and could least afford to
70
+ * read as *nothing to compare*.
71
+ */
72
+ | "from-nothing";
73
+ /** The closed set, for a surface accounting for every absent quotient. */
74
+ export declare const RATIO_ABSENCES: readonly RatioAbsence[];
75
+ /** One line per absence, for a surface saying why a ratio is not there. */
76
+ export declare const describeRatioAbsence: (absence: RatioAbsence) => string;
77
+ /**
78
+ * A quotient of the later window's figure by the earlier one's, or the reason
79
+ * there is none.
80
+ *
81
+ * `ratio` and `absent` are exclusive: exactly one of them is non-null in every
82
+ * value this module produces, which is the property that makes a surface
83
+ * reading one of them safe to write.
84
+ */
85
+ export type Ratio = {
86
+ /** `now ÷ was`, or `null` where {@link absent} says why there is none. */
87
+ readonly ratio: number | null;
88
+ /** Why there is no quotient, or `null` where there is one. */
89
+ readonly absent: RatioAbsence | null;
90
+ };
91
+ /**
92
+ * The later window's figure over the earlier one's, with the absence named.
93
+ *
94
+ * `undefined` and `null` are both *this side has no such figure*, because the
95
+ * readings this serves spell a withheld figure both ways — `undefined` on a
96
+ * part of a reading, `null` on a side of a comparison — and a helper that made
97
+ * a caller normalise first would be a fourth thing to get wrong.
98
+ *
99
+ * Nought on the earlier side is an absence rather than infinity, which is the
100
+ * rule all three copies of this already had: a ratio is a figure a surface
101
+ * divides and ranks by, and the thing that happened is told by the two sides
102
+ * and by the movement between them.
103
+ *
104
+ * Nought on the **later** side is a quotient of nought and is published as one.
105
+ * *Readers used this twice each and do not touch it now* is a measurement.
106
+ */
107
+ export declare const ratioOf: (was: number | null | undefined, now: number | null | undefined) => Ratio;
108
+ //# sourceMappingURL=ratios.d.ts.map
@@ -0,0 +1,40 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ /** The closed set, for a surface accounting for every absent quotient. */
3
+ export const RATIO_ABSENCES = everyMemberOf()([
4
+ "unmeasured",
5
+ "from-nothing",
6
+ ]);
7
+ /** One line per absence, for a surface saying why a ratio is not there. */
8
+ export const describeRatioAbsence = (absence) => {
9
+ switch (absence) {
10
+ case "unmeasured":
11
+ return "one of the two windows did not measure this, so there is nothing to divide";
12
+ case "from-nothing":
13
+ return "the earlier window measured nought, so there is no quotient to take";
14
+ }
15
+ };
16
+ /**
17
+ * The later window's figure over the earlier one's, with the absence named.
18
+ *
19
+ * `undefined` and `null` are both *this side has no such figure*, because the
20
+ * readings this serves spell a withheld figure both ways — `undefined` on a
21
+ * part of a reading, `null` on a side of a comparison — and a helper that made
22
+ * a caller normalise first would be a fourth thing to get wrong.
23
+ *
24
+ * Nought on the earlier side is an absence rather than infinity, which is the
25
+ * rule all three copies of this already had: a ratio is a figure a surface
26
+ * divides and ranks by, and the thing that happened is told by the two sides
27
+ * and by the movement between them.
28
+ *
29
+ * Nought on the **later** side is a quotient of nought and is published as one.
30
+ * *Readers used this twice each and do not touch it now* is a measurement.
31
+ */
32
+ export const ratioOf = (was, now) => {
33
+ if (was === null || was === undefined || now === null || now === undefined) {
34
+ return { ratio: null, absent: "unmeasured" };
35
+ }
36
+ if (was === 0)
37
+ return { ratio: null, absent: "from-nothing" };
38
+ return { ratio: now / was, absent: null };
39
+ };
40
+ //# sourceMappingURL=ratios.js.map