@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,333 @@
1
+ import { readingKeyOf } from "./audiences.js";
2
+ import { atDoorScale, doorOf } from "./door.js";
3
+ import { paceStandingOf, readingPaceOf, READING_WORDS_PER_MINUTE, } from "./pace.js";
4
+ import { pageViewsFor } from "./page-views.js";
5
+ /**
6
+ * Whether the readers who reach **one part** have time for what it says, across
7
+ * every page it stands on.
8
+ *
9
+ * A goal is a kind of signal on a part
10
+ * ([0350](../../decisions/0350-a-project-sets-goals-from-signals-already-collected-and-one-of-them-is-primary.md)):
11
+ * one node id, counted on the pages a project named or on every page that has
12
+ * it. Every figure a goal has is therefore keyed on a part across pages — and
13
+ * **the one a screen has been waiting for since 8 November is how long readers
14
+ * stay on it**, which `docs/portal.md` records twice as *waiting on time on a
15
+ * part being counted per reader*.
16
+ *
17
+ * The time was already in the rows. A tally carries `dwellMs` beside `reached`
18
+ * for every part of every revision, and [`pace.ts`](pace.ts) has divided the
19
+ * two for a part of **one** page since it landed. What was unaskable is the
20
+ * same question of a part that stands on nine pages: a goal's part has nine
21
+ * rows, nine word counts and nine doors, and nothing added them up. So this is
22
+ * the join, and it is the **twenty-third** thing taken out of what this
23
+ * subsystem already knows rather than collected: no payload field, no counter,
24
+ * no column, no byte on any wire and nothing in a browser.
25
+ *
26
+ * ## It is `library-pace.ts`' arithmetic keyed on a node instead of a kind
27
+ *
28
+ * [`library-pace.ts`](library-pace.ts) answers the same question of a *kind* of
29
+ * part (0325) and this one shares its terms exactly, deliberately and by
30
+ * reading its published pieces rather than by respelling them: a pooled
31
+ * quotient of two reader-millisecond sums, `dwellMs` added as the rows hold it
32
+ * and `readers × wordsWithin × msPerWord` as the denominator, each page's
33
+ * readers put on its **own** door's scale before two pages are added (0250),
34
+ * the verdict taken by {@link paceStandingOf} so that a floor can hold up
35
+ * anything but `skimmed`, and a page the door cannot scale kept rather than
36
+ * refused, because the missing correction only ever moves a pace towards the
37
+ * safe verdict.
38
+ *
39
+ * **A goal's part is not a kind of part**, which is why this is a reading and
40
+ * not a row of that one. A kind pools every placement of a type; a goal names
41
+ * one node, and the type row a screen could have read instead holds the
42
+ * forty-nine other sections of the deployment. Nothing in the library readings
43
+ * can narrow to a node, and a surface narrowing one by hand would be dividing
44
+ * two columns with none of the five rules above applied to them.
45
+ *
46
+ * ## Nothing nests, and that is the whole of what this reading does not need
47
+ *
48
+ * A kind's pace carries a nesting rule, because a stack inside a stack would
49
+ * put one page's words into one row twice. **A node id stands at most once in a
50
+ * revision**, so there is nothing here for an outer placement to stand for: one
51
+ * reading contributes one placement or none, every term is a sum over distinct
52
+ * pages, and the only way a page can enter twice is a caller handing the same
53
+ * reading in twice — which is what {@link PartPace.duplicated} counts and the
54
+ * one error that would be permanent if it were let through (0158).
55
+ *
56
+ * ## Which page it is skimmed on is the same rows, kept rather than summed away
57
+ *
58
+ * The pooled quotient is one number about nine pages, and `standings` says *and
59
+ * skimmed on two of them* without saying which two. The per-page rows were
60
+ * always there — the loop reads each page's own pace, its own words and its own
61
+ * door, and threw them away — so publishing them costs an array and no further
62
+ * arithmetic
63
+ * ([0390](../../decisions/0390-a-parts-pages-are-a-second-order-ranked-on-the-reading-time-its-readers-did-not-have.md)).
64
+ *
65
+ * The decision in it is the **order**, and it is this subsystem's ordinary one:
66
+ * the pages are ranked on the reading time their readers did not have, a
67
+ * magnitude in reader-milliseconds, rather than on the pace, a rate. A page one
68
+ * reader hurried past has the worst rate in the deployment and is not the page
69
+ * to go to (0250, 0377).
70
+ *
71
+ * ## The silences are a kind's four, as values
72
+ *
73
+ * {@link KindPaceSilence} unchanged, and reused rather than respelled for the
74
+ * reason `library-pace.ts` reuses a census's two (0256): *it stands nowhere*,
75
+ * *nowhere it stands was read*, *its words could not be counted* and *it says
76
+ * nothing that takes time* are the same four states of the same quotient, and a
77
+ * twenty-third silence vocabulary naming them again would give a screen two
78
+ * names for one state and two mappings to keep in step. What is part-shaped is
79
+ * the **sentence**, which {@link describePartPaceSilence} says; the meaning a
80
+ * window publishes is `meaningOfKindPaceSilence` and stays one function.
81
+ *
82
+ * Pure. It reaches no store, no clock and no DOM, it is linear in the parts of
83
+ * the readings times the rows handed in, and nothing in it survives into a
84
+ * browser bundle.
85
+ */
86
+ /** One line per silence, for a surface saying why one part has no pace. */
87
+ export const describePartPaceSilence = (silence) => {
88
+ switch (silence) {
89
+ case "unread":
90
+ return "nothing reported a view of this part on any page it stands on";
91
+ case "unplaced":
92
+ return "none of the pages read holds this part";
93
+ case "unreadable":
94
+ return "some of its words could not be counted, so only a skim could be claimed of it";
95
+ case "wordless":
96
+ return "it says nothing that takes time to read";
97
+ }
98
+ };
99
+ const NO_STANDINGS = Object.freeze({
100
+ skimmed: 0,
101
+ paced: 0,
102
+ lingered: 0,
103
+ unknown: 0,
104
+ });
105
+ const NO_SILENCES = Object.freeze({
106
+ unreached: 0,
107
+ unreadable: 0,
108
+ wordless: 0,
109
+ });
110
+ /**
111
+ * Tree id, then newest revision first, which is the order the page-view rows
112
+ * are read in — and the last key of every list this module publishes, so two
113
+ * pages that cost the same do not reorder on a refresh.
114
+ */
115
+ const byRevision = (one, other) => one.treeId.localeCompare(other.treeId) || other.revision - one.revision;
116
+ /**
117
+ * Most reading time missing, then the lower pace, then by page (0390).
118
+ *
119
+ * Both keys are the row's own, and the second is only ever reached by pages
120
+ * whose readers had time enough — `shortMs` is nought exactly where `pace` is
121
+ * at least `1`, so the tie-break ranks the pages nearest to being short.
122
+ */
123
+ const byTimeMissing = (one, other) => other.shortMs - one.shortMs || one.pace - other.pace || byRevision(one, other);
124
+ const MS_PER_MINUTE = 60_000;
125
+ /** A positive, finite option, or the fallback. Everything else is refused. */
126
+ const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
127
+ /**
128
+ * The silence, with the reasons tried in the order they have to be tried in.
129
+ *
130
+ * *It stands nowhere* before *nowhere was read*, because the second is true of
131
+ * the first by accident. Then the part-level reasons in the order a page's own
132
+ * reading reaches them: a floor before silence, because *nobody counted them*
133
+ * outranks *there are none*.
134
+ */
135
+ const silenceOf = (placements, counted, silences, standing) => {
136
+ if (placements === 0)
137
+ return "unplaced";
138
+ if (counted === 0) {
139
+ if (silences.unreadable > 0)
140
+ return "unreadable";
141
+ if (silences.wordless > 0)
142
+ return "wordless";
143
+ return "unread";
144
+ }
145
+ return standing === "unknown" ? "unreadable" : null;
146
+ };
147
+ /**
148
+ * Whether the readers who reach one part have time for what it says.
149
+ *
150
+ * Takes the node, the readings of the pages it is counted on, and the whole
151
+ * window of page-view rows a deployment holds — each page's own row is picked
152
+ * out of them by the published matching rule (`pageViewsFor`) rather than by a
153
+ * hand-written copy of it, because the pairing is the part of every join here
154
+ * that fails quietly when it is got wrong.
155
+ *
156
+ * **Which readings are handed in is the caller's answer to *which pages*.** A
157
+ * goal naming pages hands in those pages' readings; a goal naming none hands in
158
+ * every page it can read, and a reading with no row for the node contributes
159
+ * nothing but a count. Narrowing here rather than inside would have made this
160
+ * function hold the goal vocabulary, which is the portal's and not this
161
+ * subsystem's (0350).
162
+ *
163
+ * There is **no `inflation` option**, for the reason `libraryPaceOf` has none:
164
+ * one scalar over nine pages with nine straddle rates would be a correction
165
+ * nobody measured, so each page's own is read off its own door row.
166
+ *
167
+ * Linear in the parts of the readings times the rows.
168
+ */
169
+ export const partPaceOf = (nodeId, readings, rows, options = {}) => {
170
+ const wordsPerMinute = positive(options.wordsPerMinute, READING_WORDS_PER_MINUTE);
171
+ const msPerWord = MS_PER_MINUTE / wordsPerMinute;
172
+ const seen = new Set();
173
+ const trees = new Set();
174
+ const bearing = new Set();
175
+ const unscaledPages = [];
176
+ const disagreed = new Set();
177
+ const standings = { ...NO_STANDINGS };
178
+ const silences = { ...NO_SILENCES };
179
+ const ranked = [];
180
+ const unranked = [];
181
+ let type = null;
182
+ let role = null;
183
+ let placements = 0;
184
+ let counted = 0;
185
+ let floored = 0;
186
+ let whole = 0;
187
+ let readers = 0;
188
+ let dwellMs = 0;
189
+ let needMs = 0;
190
+ let unscaled = 0;
191
+ let duplicated = 0;
192
+ let duplicatedRows = 0;
193
+ for (const reading of readings) {
194
+ const key = readingKeyOf(reading);
195
+ if (seen.has(key)) {
196
+ duplicated += 1;
197
+ continue;
198
+ }
199
+ seen.add(key);
200
+ const found = pageViewsFor(reading, rows);
201
+ duplicatedRows += found.duplicated;
202
+ const door = doorOf(found.measured);
203
+ /**
204
+ * Each page's own straddle rate, off its own door (0250). A page the door
205
+ * cannot scale gets no correction, which leaves its pace low rather than
206
+ * high.
207
+ */
208
+ const paced = readingPaceOf(reading, {
209
+ inflation: found.measured?.inflation ?? 0,
210
+ wordsPerMinute,
211
+ });
212
+ const part = paced.parts.find((candidate) => candidate.nodeId === nodeId);
213
+ if (part === undefined)
214
+ continue;
215
+ placements += 1;
216
+ if (placements === 1) {
217
+ type = part.type;
218
+ role = part.role;
219
+ }
220
+ else if (part.type !== type) {
221
+ disagreed.add(part.type);
222
+ }
223
+ standings[part.standing] += 1;
224
+ const scaled = door.silence === null ? atDoorScale(part.readers, door) : part.readers;
225
+ /**
226
+ * What this page is, before it is known whether it has figures — the half
227
+ * of a row that both lists carry, and the half that is the same question
228
+ * either way.
229
+ *
230
+ * `standing` is the page's **own** reading's verdict and never one
231
+ * re-derived from the row's `pace` below. The two quotients agree
232
+ * mathematically and need not agree in their last float place, and
233
+ * `standings` counts this one — so a breakdown of *skimmed on two of them*
234
+ * that recomputed the verdict could name three pages or one (0390).
235
+ */
236
+ const where = {
237
+ treeId: reading.treeId,
238
+ revision: reading.revision,
239
+ audienceId: reading.audienceId,
240
+ readers: scaled,
241
+ dwellMs: part.dwellMs,
242
+ wordsWithin: part.wordsWithin,
243
+ floored: part.floored,
244
+ whole: part.depth === 0,
245
+ unscaled: door.silence,
246
+ standing: part.standing,
247
+ };
248
+ if (part.pace === null) {
249
+ /**
250
+ * A part with no pace always carries the reason it has none, because
251
+ * `pace.ts` fills the silence for every standing of `unknown` and a part
252
+ * with no pace is always one. The fallback is the type system's and not a
253
+ * state.
254
+ */
255
+ const silence = part.silence ?? "unreached";
256
+ silences[silence] += 1;
257
+ unranked.push({ ...where, needMs: null, spentMs: null, shortMs: null, pace: null, silence });
258
+ continue;
259
+ }
260
+ /**
261
+ * The page's own terms, in the reader-milliseconds the sums are in — never
262
+ * `PacedPart.needMs`, which is one reader's. Taking the row's figures off
263
+ * the same two products the sums are made of is what makes the breakdown
264
+ * add up to the figure above it, which is the only thing tying the two
265
+ * together.
266
+ */
267
+ const placeNeedMs = scaled * part.wordsWithin * msPerWord;
268
+ counted += 1;
269
+ trees.add(reading.treeId);
270
+ bearing.add(key);
271
+ floored += part.floored ? 1 : 0;
272
+ whole += part.depth === 0 ? 1 : 0;
273
+ readers += scaled;
274
+ dwellMs += part.dwellMs;
275
+ needMs += placeNeedMs;
276
+ ranked.push({
277
+ ...where,
278
+ needMs: placeNeedMs,
279
+ spentMs: part.dwellMs / scaled,
280
+ shortMs: Math.max(0, placeNeedMs - part.dwellMs),
281
+ pace: part.dwellMs / placeNeedMs,
282
+ silence: null,
283
+ });
284
+ if (door.silence !== null) {
285
+ unscaled += scaled;
286
+ unscaledPages.push({
287
+ treeId: reading.treeId,
288
+ revision: reading.revision,
289
+ silence: door.silence,
290
+ });
291
+ }
292
+ }
293
+ /**
294
+ * A counted placement always has a reader and a word of its own, so a part
295
+ * with one has a denominator: `needMs` is nought exactly when `counted` is.
296
+ */
297
+ const pace = counted === 0 ? null : dwellMs / needMs;
298
+ const order = [...ranked].sort(byTimeMissing);
299
+ const standing = paceStandingOf(pace, floored > 0);
300
+ const silence = silenceOf(placements, counted, silences, standing);
301
+ const measured = silence === null;
302
+ return {
303
+ nodeId,
304
+ type,
305
+ role,
306
+ typeDisagreed: [...disagreed].sort((one, other) => one.localeCompare(other)),
307
+ placements,
308
+ counted,
309
+ silences: { ...silences },
310
+ standings: { ...standings },
311
+ pages: bearing.size,
312
+ trees: trees.size,
313
+ floored,
314
+ whole,
315
+ readers: measured ? readers : null,
316
+ dwellMs,
317
+ needMs: measured ? needMs : null,
318
+ spentMs: measured ? dwellMs / readers : null,
319
+ shortMs: measured ? Math.max(0, needMs - dwellMs) : null,
320
+ pace: measured ? pace : null,
321
+ standing,
322
+ silence,
323
+ unscaled,
324
+ unscaledPages: [...unscaledPages].sort(byRevision),
325
+ duplicated,
326
+ duplicatedRows,
327
+ ranked: order,
328
+ unranked: [...unranked].sort(byRevision),
329
+ worst: order[0] ?? null,
330
+ wordsPerMinute,
331
+ };
332
+ };
333
+ //# sourceMappingURL=part-pace.js.map
@@ -0,0 +1,354 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { NodeId, TreeId } from "../ids.js";
3
+ import type { PrimitiveType } from "../primitive-type.js";
4
+ import { type PrimitiveRole } from "../role.js";
5
+ import type { CopyDeclarations, NodeCopy } from "../sdk/copy.js";
6
+ import type { LoomTree } from "../tree/tree.js";
7
+ import { type MaybeAudienceScoped } from "./audiences.js";
8
+ import { type RoleDeclarations } from "./join.js";
9
+ import type { ReaderTally } from "./rollup.js";
10
+ /**
11
+ * What a counter is about, joined on the server from what the page already
12
+ * knows.
13
+ *
14
+ * A batch names a node, a tree and a revision, and nothing else — that is rule 1
15
+ * of [`docs/signals.md`](../../docs/signals.md) and it is not negotiable. The
16
+ * browser therefore has two attributes on an element and no idea that `n_42` is
17
+ * a pricing band, that its primitive declares itself a heading (0114), or which
18
+ * of its props a reader reads (0122).
19
+ *
20
+ * **The server has all three.** Intake and rollup both hold the registry and the
21
+ * tree the batch names, so `dwelled on n_42` becomes *eleven seconds on a
22
+ * pricing band, whose words were these* with no byte added to the payload, no
23
+ * browser change, and no new decision about what to keep.
24
+ * [0167](../../decisions/0167-a-delegated-signal-names-the-regions-it-happened-inside.md)
25
+ * refused ancestry on the high-volume kinds for exactly this reason — payload
26
+ * multiplied by page depth, to buy what the server could derive — and the same
27
+ * argument covers roles, parts and copy.
28
+ *
29
+ * ## The thing only a tree can say
30
+ *
31
+ * Counters answer what happened. They cannot answer what *did not*, because a
32
+ * part nobody reached has no row: absence of a tally is absence of data, and a
33
+ * list of rows can never be read as a list of the page. The tree is the
34
+ * universe — every element node in it is an addressed node, so every one of them
35
+ * is a part a reader could have reached — and against that universe silence
36
+ * becomes a measurement. *Which parts of a page are read and which are scrolled
37
+ * past* is this join and nothing else.
38
+ *
39
+ * ## Why the join is at read time and not at rollup time
40
+ *
41
+ * Rollup also holds the tree and the registry, so it could write the role and
42
+ * the words onto the counters as they are stored. It must not. A declaration is
43
+ * a fact about the library, not about a window of reading: the day
44
+ * `src/primitives/` declares `copy` across itself
45
+ * ([0122](../../decisions/0122-a-primitive-says-which-of-its-props-a-reader-reads.md)
46
+ * says nothing does yet), a read-time join reinterprets every counter already
47
+ * stored, and a rollup-time one has baked the old silence into rows that are
48
+ * expensive to revisit and impossible to correct for windows already expired.
49
+ * The counters stay node-shaped for the same reason the wire does.
50
+ *
51
+ * The tree a reading needs is the one the counters name. For the current
52
+ * revision that is the snapshot a store already holds; for an older one it is
53
+ * `replayTree` over the log, which is how *before versus after a change* reaches
54
+ * two readings.
55
+ *
56
+ * Pure. It is handed a tree, a window's counters and the declarations, and
57
+ * returns a reading; it reaches no store, no clock and no DOM, and it adds
58
+ * nothing to the broadcaster's import graph.
59
+ */
60
+ /**
61
+ * What a window of counters says about one part of a page.
62
+ *
63
+ * Three answers, and the third exists because the other two are claims. A
64
+ * reading that only said *read* or *skipped* would have to call a page nobody
65
+ * opened a page everybody skipped, which is the plausible-false-number failure:
66
+ * a figure that is the right shape, drawn on a screen, and about nothing.
67
+ *
68
+ * **Every combination of the three is reachable except one, and the arithmetic
69
+ * that rules it out is worth having here.** `skipped` means *no row names this
70
+ * part*, and {@link PageReading.views} is the largest `views` any one row
71
+ * reports — both read off the same rows. So every part being `skipped` would
72
+ * need the window to hold no row for any part of the page, which makes `views`
73
+ * zero, which makes every part `unknown` instead. *A page with visits, every
74
+ * part of which went unseen* cannot be drawn from counters, and the one input
75
+ * that produces it is a row naming a node this revision does not have — which is
76
+ * {@link PageReading.orphaned}, and is the one state a consumer should refuse to
77
+ * draw rather than render.
78
+ *
79
+ * The reachable neighbour is the one worth a screen: **rows exist and not one
80
+ * reports reach.** A root is addressed and is in the viewport of every view that
81
+ * draws the page, so that is a page whose parts are not reporting — a primitive
82
+ * not spreading its identity attributes, or a sender switched on halfway through
83
+ * a release — and not a page nobody scrolled. Filed by `Loom portal` on 2 October
84
+ * after a test that tried to build the impossible state and could not.
85
+ */
86
+ export type PartStanding =
87
+ /** At least one view reported it coming into view. */
88
+ "read"
89
+ /**
90
+ * The window held views of this revision, and none of them said anything
91
+ * about this part at all.
92
+ *
93
+ * It was on the page and in nobody's viewport. The one caveat is in the render
94
+ * rather than here: a primitive that does not spread its identity attributes
95
+ * is invisible to the broadcaster and reads as skipped, which is what
96
+ * `sdk/conformance.ts` exists to catch.
97
+ */
98
+ | "skipped"
99
+ /**
100
+ * Nothing can be said.
101
+ *
102
+ * Either the window held no views of this revision — so every part is
103
+ * unknown, and *skipped* would be a statement about readers who were not
104
+ * there — or the part reported something other than coming into view. The
105
+ * second is rarer and sharper: a press was delegated to a band that no
106
+ * `viewed` ever named, so a reader plainly had it in front of them and the
107
+ * counter that would say so is missing. Calling that skipped would be a lie
108
+ * in the direction nobody checks.
109
+ */
110
+ | "unknown";
111
+ export declare const PART_STANDINGS: readonly PartStanding[];
112
+ /**
113
+ * Whether the window can say either way, which is the one question every
114
+ * figure over a page's words is restricted by.
115
+ *
116
+ * `read` and `skipped` are claims about readers; `unknown` is the absence of
117
+ * one (0282). A passage nothing can be said about is in no mass, out of every
118
+ * list a person acts on, and outside the denominator of every share
119
+ * ([0287](../../decisions/0287-a-share-of-a-pages-words-is-a-share-of-the-words-the-window-can-speak-for-and-spoken-for-is-one-predicate.md)).
120
+ *
121
+ * **Published here rather than spelled where it is asked.** Three modules
122
+ * enumerated the standing by hand and a fourth was about to, and the way that
123
+ * breaks is a sixth `PartStanding`: one spelling has to be revisited and the
124
+ * others go on agreeing with the version of the vocabulary they were written
125
+ * against. Two spellings of a projection that agree today are what the counter
126
+ * keys were before they were published once.
127
+ *
128
+ * **It is not `anchors`.** `change.ts` and `progress.ts` ask the same question
129
+ * of a part under a different name, because what 0221 needs is *can this part
130
+ * anchor a stop* and the answer coincides. A predicate shared because two
131
+ * rules agree is the thing this is fixing.
132
+ */
133
+ export declare const spokenFor: (standing: PartStanding) => boolean;
134
+ /** One line per standing, for a surface putting the reading in front of a person. */
135
+ export declare const describePartStanding: (standing: PartStanding) => string;
136
+ export type { RoleDeclarations } from "./join.js";
137
+ /** Everything the join asks of a deployment. A `PrimitiveRegistry` satisfies it. */
138
+ export type PartDeclarations = CopyDeclarations & RoleDeclarations;
139
+ /**
140
+ * One element node of one revision, with whatever the window said about it.
141
+ *
142
+ * In reading order, with the depth and parent an outline carries, because *which
143
+ * parts are read* is a question about a page from the top down: the shape of the
144
+ * answer is where in the page the reading stops, and a set of rows keyed by id
145
+ * cannot show it.
146
+ */
147
+ export type PartReading = {
148
+ readonly nodeId: NodeId;
149
+ readonly type: PrimitiveType;
150
+ /** What part it plays (0114), or `null` where its type declared none. */
151
+ readonly role: PrimitiveRole | null;
152
+ /** 0 at the root. */
153
+ readonly depth: number;
154
+ /**
155
+ * The **tree** parent, which may be a node that is in no part's list, and
156
+ * `null` at the root.
157
+ *
158
+ * A slot is a node with children and is never a part, so an element handed
159
+ * into a slot has a slot's id here — an id that appears nowhere in
160
+ * {@link PageReading.parts}. Kept because three readings and the published
161
+ * reference carry it and it is the right answer to the question it asks, which
162
+ * is *where is this node in the tree*. {@link PartReading.withinId} is the
163
+ * answer to the other one.
164
+ */
165
+ readonly parentId: NodeId | null;
166
+ /**
167
+ * The nearest **addressed** ancestor — the part this part sits inside — and
168
+ * `null` at the outermost part.
169
+ *
170
+ * What a surface drawing the page's shape must key on, and what `within`
171
+ * names on the wire (0167): slots between two elements are passed through, so
172
+ * every id here is one this list has a row for. The same field, by the same
173
+ * rule, as `InsidePart.withinId` (0368) — one page has one containment, and
174
+ * two readings of it must not disagree about what contains what.
175
+ */
176
+ readonly withinId: NodeId | null;
177
+ readonly standing: PartStanding;
178
+ /**
179
+ * The counters, or `undefined` where no signal in the window named it.
180
+ *
181
+ * Undefined is not zero and is kept apart from it on purpose. A part with a
182
+ * row of zeroes was reported on; a part with no row was not, and the
183
+ * difference is the whole of how `skipped` is told from a quiet page.
184
+ */
185
+ readonly counters: ReaderTally | undefined;
186
+ /**
187
+ * The words this part says itself: its declared copy props, and the text
188
+ * handed to it directly or through a slot.
189
+ *
190
+ * **Its own, never its subtree's.** Neither a text node nor a slot node is an
191
+ * element, so neither can ever be a part of its own and the words handed into
192
+ * one would otherwise be lost; every other descendant is a part in this same
193
+ * list. So the words of a page are
194
+ * partitioned across its parts exactly once, and a caller may add two rows
195
+ * together without reading a headline twice.
196
+ *
197
+ * `unread` and `unspoken` mean what they mean in the reading they come from
198
+ * (0122): nobody has said whether these props are words, and somebody said
199
+ * these were words and what is in them is not one. The starter library
200
+ * declares `copy` across itself (0223), so `unread` on a page built from it
201
+ * is a deployment's own primitives rather than the framework's silence.
202
+ */
203
+ readonly copy: NodeCopy;
204
+ };
205
+ /**
206
+ * Every part playing one role, added up.
207
+ *
208
+ * **Occurrences only.** `dwellMs`, `activations`, `opens`, `closes` and
209
+ * `completions` are counts of things that happened and they add up across parts.
210
+ * `views`, `reached` and `engaged` count *distinct page views* and are
211
+ * deliberately absent: one reader who read three headings is three in a sum of
212
+ * `reached` and one actual person, which is the distinctness trap 0147 already
213
+ * wrote down one level up. What a role row says about views instead is
214
+ * `standings` — how many of its parts were read, skipped, or cannot be spoken
215
+ * for — which is a count of parts and cannot be mistaken for a count of readers.
216
+ *
217
+ * **`engaged` is absent for a second reason as well.** A press inside a band is
218
+ * one `activations` on the button and one `engaged` on the band, by design
219
+ * (0167). Adding both into one row would count a single reader's single action
220
+ * twice, and the row would look right.
221
+ */
222
+ export type RoleReading = {
223
+ /** `null` is the row for parts whose type declared no role, which is most of a page today. */
224
+ readonly role: PrimitiveRole | null;
225
+ /** Element nodes of this revision playing it. */
226
+ readonly parts: number;
227
+ readonly standings: Readonly<Record<PartStanding, number>>;
228
+ readonly dwellMs: number;
229
+ readonly activations: number;
230
+ readonly opens: number;
231
+ readonly closes: number;
232
+ readonly completions: number;
233
+ };
234
+ export type PageReading = {
235
+ readonly treeId: TreeId;
236
+ readonly revision: number;
237
+ /**
238
+ * The audience whose counters this reading is of, or `null` where nothing
239
+ * said.
240
+ *
241
+ * `null` has two causes and they are a long way apart. A window whose rows
242
+ * never named an audience is one population by construction and is read
243
+ * whole — which is every window written before the column existed (0284) and
244
+ * every one a test builds by hand. A window naming **two**, handed in without a caller saying
245
+ * which was wanted, is two populations and is read as neither: see
246
+ * {@link PageReading.audiences}.
247
+ */
248
+ readonly audienceId: AudienceId | null;
249
+ /**
250
+ * Every audience the window named, whether or not it was the one read.
251
+ *
252
+ * More than one member with {@link PageReading.audienceId} `null` is the
253
+ * refusal: a page served in two forms (0263) has two sets of counters over
254
+ * one tree at one revision, and adding them is one number about two
255
+ * populations, which is the collapse a dimension on the rows exists to
256
+ * prevent (0284). Nothing is read, every part is
257
+ * `unknown`, and the caller is told what it was holding so it can split
258
+ * (`byAudience`) and read twice.
259
+ */
260
+ readonly audiences: readonly AudienceId[];
261
+ /**
262
+ * Counters filed under this tree and revision, in an audience other than the
263
+ * one read, and ignored.
264
+ *
265
+ * Not `foreign`, which is about a page, and not `duplicated`, which is about
266
+ * a row handed in twice. A deployment reading one form's counters out of a
267
+ * window holding both of them is doing the right thing, and this is how much
268
+ * of that window belonged to the other form.
269
+ */
270
+ readonly otherAudience: number;
271
+ /**
272
+ * A floor on the page views the window held, not a count of them.
273
+ *
274
+ * The largest `views` any single part reports. A view that produced no signal
275
+ * about any part is in no row at all, and distinct view counts cannot be added
276
+ * across rows (0147), so the largest row is the most that can be said from
277
+ * counters alone. It is a good floor in practice because a page root is an
278
+ * addressed node and a root is in the viewport of every view that renders.
279
+ *
280
+ * Zero is what makes every standing `unknown`: nothing was measured, so
281
+ * nothing was skipped.
282
+ */
283
+ readonly views: number;
284
+ /** Every element node, in reading order. */
285
+ readonly parts: readonly PartReading[];
286
+ /** Every role in the vocabulary, then the row for parts that declared none. */
287
+ readonly roles: readonly RoleReading[];
288
+ readonly standings: Readonly<Record<PartStanding, number>>;
289
+ /**
290
+ * Counters handed in that are filed under another tree or another revision,
291
+ * and were ignored.
292
+ *
293
+ * Adding two revisions of a node together is the mistake that makes *before
294
+ * versus after a change* unreadable, so this filters rather than trusts its
295
+ * caller — and says how much it dropped, because a caller who passed a whole
296
+ * store's rows and a caller who passed the wrong revision's look identical
297
+ * from the inside.
298
+ */
299
+ readonly foreign: number;
300
+ /**
301
+ * Counters filed under this tree and revision, naming a node this tree does
302
+ * not contain.
303
+ *
304
+ * The alarm for the one failure this join can have that nothing else would
305
+ * catch: a tree and a window that do not belong together. Pass revision 7's
306
+ * counters with revision 6's tree and most parts read `skipped` while the
307
+ * numbers stay plausible. A non-empty list here says the pair is wrong, and
308
+ * names the rows that prove it.
309
+ */
310
+ readonly orphaned: readonly NodeId[];
311
+ /**
312
+ * Nodes handed in more than once, where every row but the first was ignored.
313
+ *
314
+ * A store keeps one row per node per revision per audience (0284) and the
315
+ * audience is picked before this is counted, so this cannot happen from one
316
+ * read — it happens when a caller concatenates two windows instead of letting
317
+ * the store add them. Neither available answer is right: summing is wrong
318
+ * because `views`, `reached` and `engaged` count distinct views and
319
+ * distinctness cannot be added (0147), and overwriting is wrong because the
320
+ * later row is not the truer one. So the first row stands, the rest are
321
+ * dropped, and the fact is reported rather than being a quiet halving of
322
+ * somebody's dwell time.
323
+ */
324
+ readonly duplicated: readonly NodeId[];
325
+ };
326
+ /**
327
+ * Join a window's counters to the tree and registry they were filed against.
328
+ *
329
+ * The tree carries the pair the counters are keyed by, so there is no way to ask
330
+ * this question about a revision without holding the revision — which is the
331
+ * property that makes the answer trustworthy. Rows filed under anything else are
332
+ * dropped and counted.
333
+ *
334
+ * **A reading is of one audience.** A page is one base tree and the deltas an
335
+ * audience earns (0263), so two forms of it are two sets of counters over one
336
+ * tree at one revision, told apart by a column and nothing else (0284). Name
337
+ * the audience and the rest of the window is `otherAudience`; name none and a
338
+ * window holding one audience, or none at all, is read whole. A window holding
339
+ * two with none named is read as neither, because the only other answers are
340
+ * summing two populations and picking one of them by row order.
341
+ */
342
+ export declare const pageReadingOf: (tree: LoomTree, tallies: readonly (ReaderTally & MaybeAudienceScoped)[], declarations: PartDeclarations, audience?: AudienceId) => PageReading;
343
+ /**
344
+ * The words readers actually reached, in reading order.
345
+ *
346
+ * The third question step 6 names, and it is a filter rather than a build: a
347
+ * part's words are its own, so concatenating the read ones double-counts
348
+ * nothing. What it cannot include is a word whose part declared no `copy` —
349
+ * those are in each part's `copy.unread`, named, because a reading that returned
350
+ * them would be guessing and one that dropped them silently would be the failure
351
+ * 0122 exists to prevent.
352
+ */
353
+ export declare const wordsReadIn: (reading: PageReading) => readonly string[];
354
+ //# sourceMappingURL=parts.d.ts.map