@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,306 @@
1
+ import type { PrimitiveType } from "../primitive-type.js";
2
+ import { type PrimitiveRole } from "../role.js";
3
+ import { type PageReading, type PartStanding } from "./parts.js";
4
+ /**
5
+ * Whether a *kind* of part gets read, across every page it is on.
6
+ *
7
+ * Every reading in this subsystem answers about one page: where its reading
8
+ * stops, how much of what it says gets read, what a change did to it.
9
+ * [`deployment.ts`](deployment.ts) is the first that is larger than a page, and
10
+ * it is still an order **over** pages — the unit it ranks is a page and the
11
+ * answer it gives is *fix this one next*.
12
+ *
13
+ * **Nothing could be asked about a kind of part.** A deployment builds forty
14
+ * pages out of the same two dozen primitives, and *do readers read the
15
+ * testimonial band anywhere* is a question about the **library** rather than
16
+ * about any one page. It is the question a model proposing a change most wants
17
+ * answered before it proposes one, and it was the one question the counters
18
+ * could not be asked: a type's placements are scattered across forty readings
19
+ * and nothing joined them.
20
+ *
21
+ * This is that join, taken off the readings a deployment already has and
22
+ * nothing else: no payload, no browser change, no counter that does not exist,
23
+ * no column and no byte on any wire. It is the **fourteenth** thing derived
24
+ * from what the server already knows rather than collected.
25
+ *
26
+ * ## The unit is the placement, and a reader is never the unit
27
+ *
28
+ * A page is a part of a revision of a tree; a **placement** is one element node
29
+ * of one revision, which is exactly what a `PartReading` is. So a type's row
30
+ * counts placements: *`loom.testimonial` stands in nine places and readers
31
+ * reached two of them.*
32
+ *
33
+ * **Everything that counts readers is absent from these rows**, and the reason
34
+ * is not caution. `views`, `reached` and `engaged` count distinct page views, and
35
+ * distinctness cannot be added — one reader who read a heading on three pages is
36
+ * three in a sum of `reached` and one person
37
+ * ([0147](../../decisions/0147-a-rollup-is-added-to-what-is-stored-and-a-distinct-view-count-is-therefore-approximate.md)).
38
+ * A `RoleReading` already refuses them one level down for the same reason
39
+ * ([0212](../../decisions/0212-what-a-reader-signal-means-is-joined-to-the-tree-when-it-is-read.md)),
40
+ * and across pages it is worse rather than better: each page's distinct counts
41
+ * are inflated by **its own** straddle rate, which is the fact that put every
42
+ * page's loss on the door's scale before it could be ranked
43
+ * ([0250](../../decisions/0250-a-deployment-is-ordered-by-readers-lost-at-the-doors-scale-and-a-page-the-door-cannot-scale-is-out-of-the-order.md)).
44
+ *
45
+ * A share of **placements** has none of that in it. `read ÷ (read + skipped)` is
46
+ * a ratio of two counts of parts of trees, so no reader is counted at all, no
47
+ * rollup window appears in either term, and shortening a deployment's window
48
+ * cannot move it. That is what makes it the figure this reading leads with.
49
+ *
50
+ * ## What that costs, said plainly
51
+ *
52
+ * **A placement on a page nine thousand people read counts the same as one on a
53
+ * page three people read.** A kind read in the one busy place and skipped in
54
+ * nine quiet ones reports a read share of one in ten, and *most readers who met
55
+ * it read it* would also have been true. The share is about places and never
56
+ * about people, and a surface that prints it as *readers skip this* is printing
57
+ * something this reading did not say.
58
+ *
59
+ * **The weighted figure is a different question and needs the door.** Weighting
60
+ * each placement by its page's readers means `reached ÷ views` per placement and
61
+ * a mean over them — two distinct counts, each inflated by its own page's
62
+ * straddle, so the pages whose readers linger would weigh most and a deployment
63
+ * that shortened its rollup window would see the figure move with no reader
64
+ * moving. The correction exists and is `opened` at the door (0250), so the
65
+ * question is answerable and is not answered here; it is filed rather than
66
+ * shipped with a caveat.
67
+ *
68
+ * **A share of placements multiplied by anything is not a count of people.** A
69
+ * share of one part of a page times the page's readership was a count of people
70
+ * larger than the page had, found on a reader card on 8 October; a share of
71
+ * places times a readership is worse, because its denominator is not people in
72
+ * the first place.
73
+ *
74
+ * ## Why a count of places is worth having anyway
75
+ *
76
+ * Because the three sentences it supports are the ones an author can act on, and
77
+ * none of them needs a reader to be counted:
78
+ *
79
+ * - *this kind of part is skipped in seven of the nine places it stands* — a
80
+ * fact about the library, which is a reason to change the primitive rather
81
+ * than the page;
82
+ * - *this kind says four thousand words and readers reached three hundred of
83
+ * them* — words partition a page exactly once (0212), so they add across
84
+ * placements without counting a sentence twice;
85
+ * - *this kind was used eleven hundred times* — an occurrence, filed against the
86
+ * part the reader used, so no press is counted twice (0167).
87
+ *
88
+ * ## The one figure that nests, and the total this does not publish
89
+ *
90
+ * `dwellMs` is time on screen, and a part is on screen while its children are.
91
+ * So one second a reader spent in a band is in the band's row **and** in the
92
+ * row of everything inside it, and that is true of a `RoleReading`'s dwell
93
+ * already. Within a kind it is a volume of attention and is useful as one; added
94
+ * **across** kinds it is not a duration anybody spent, so there is no
95
+ * reading-wide dwell here and there will not be one.
96
+ *
97
+ * Nor is there a deployment-wide `placements` share or a single headline number
98
+ * over the kinds. The artefact is a census, and the only error available to a
99
+ * census is counting the same page twice — which is the one thing deduplicated
100
+ * here (0158: counting a window and forgetting it are one operation).
101
+ *
102
+ * Pure. It reaches no store, no clock and no DOM, it is linear in the parts of
103
+ * the readings handed to it, and nothing in it survives into a browser bundle.
104
+ */
105
+ /** Why a kind's read share is not there. */
106
+ export type KindSilence =
107
+ /**
108
+ * No placement of it has a verdict: every page it stands on held no views, or
109
+ * reported something other than a view of it.
110
+ *
111
+ * Not *nobody read it*. A placement whose standing is `unknown` is in a window
112
+ * that said nothing, and the one direction a census of a quiet deployment must
113
+ * not be wrong in is calling that a skip (0212). The placements are still counted and still in {@link KindReading.standings};
114
+ * what is withheld is the share, because its denominator would be nought.
115
+ */
116
+ "unread"
117
+ /**
118
+ * Nothing in the pages read is of this kind at all.
119
+ *
120
+ * Only ever a role row, and it is the reason a role row exists for every
121
+ * member of the vocabulary: *nothing in this library is a heading* is a fact
122
+ * about the library, and a surface that had to tell a missing row from an
123
+ * empty one would be reading the vocabulary itself. A type row cannot be in
124
+ * this state, because a type row exists only where a part of that type stands.
125
+ *
126
+ * Kept apart from {@link KindSilence} `unread` because the two are opposite
127
+ * instructions: one says measure more, the other says there is nothing here to
128
+ * measure.
129
+ */
130
+ | "unplaced";
131
+ export declare const KIND_SILENCES: readonly KindSilence[];
132
+ /** One line per silence, for a surface saying why a kind has no share. */
133
+ export declare const describeKindSilence: (silence: KindSilence) => string;
134
+ /** What a row is a census of: one primitive type, or one role, across the pages read. */
135
+ export type KindKey = {
136
+ readonly by: "type";
137
+ readonly type: PrimitiveType;
138
+ }
139
+ /** `null` is the row for parts whose type declared no role, which is most of a library today. */
140
+ | {
141
+ readonly by: "role";
142
+ readonly role: PrimitiveRole | null;
143
+ };
144
+ /** A key as a string, for a surface keying a list and for this module's own grouping. */
145
+ export declare const kindKeyOf: (kind: KindKey) => string;
146
+ /**
147
+ * One kind of part, everywhere it stands in the pages read.
148
+ *
149
+ * The same shape for a type row and a role row, because they are one census
150
+ * asked of two keys: a type is what an author can change and a role is what a
151
+ * reader meets, and a figure that meant different things in the two would be the
152
+ * kind of near-duplicate this subsystem has already been bitten by.
153
+ */
154
+ export type KindReading = {
155
+ readonly kind: KindKey;
156
+ /** What part a type plays (0114), or `null`. Always `null` on a role row, which carries it as its key. */
157
+ readonly role: PrimitiveRole | null;
158
+ /** Element nodes of this kind across the readings. */
159
+ readonly placements: number;
160
+ /** Distinct trees it stands in, which is not the number of placements and not the number of readings. */
161
+ readonly trees: number;
162
+ /** Distinct revisions it stands in: two live revisions of one page are two. */
163
+ readonly revisions: number;
164
+ /** Placements by standing. The three add to {@link placements}. */
165
+ readonly standings: Readonly<Record<PartStanding, number>>;
166
+ /**
167
+ * The share of its placements at least one reader reached. `null` where
168
+ * {@link silence} says why not.
169
+ *
170
+ * *At least one*, which is what a standing of `read` means and not what a
171
+ * person reads the word as (0235). `read ÷ (read + skipped)`, so a placement
172
+ * nothing can be said about is in neither term rather than counted as a skip.
173
+ *
174
+ * **Places and not people.** See the module documentation: it is sound as a
175
+ * statement about where this kind of part stands and is not a share of
176
+ * readers.
177
+ */
178
+ readonly readShare: number | null;
179
+ /**
180
+ * Why {@link readShare} is not there, and `null` where it is.
181
+ *
182
+ * About the read share and not about the row: {@link wordShare} is absent for
183
+ * a reason of its own and says so where it is, which is how a copy reading
184
+ * already publishes a share beside a withheld figure (0235).
185
+ */
186
+ readonly silence: KindSilence | null;
187
+ /**
188
+ * Every word this kind says across its placements, counted once.
189
+ *
190
+ * Addable for the reason no view count here is: a part's words are its own and
191
+ * the words of a page are partitioned across its parts exactly once (0212), so
192
+ * two placements' words are two different sentences.
193
+ */
194
+ readonly words: number;
195
+ /** Words said by a placement at least one reader reached. */
196
+ readonly wordsReached: number;
197
+ /**
198
+ * {@link wordsReached} over {@link words}; `null` where this kind says nothing
199
+ * at all, which a spacer, a rule and a stack that only holds other parts all
200
+ * do.
201
+ */
202
+ readonly wordShare: number | null;
203
+ /**
204
+ * Placements whose words are a floor, because the type declares no `copy`
205
+ * (0122).
206
+ *
207
+ * The direction {@link wordShare} is wrong in, handed over rather than
208
+ * summarised: a floored placement understates the numerator and the
209
+ * denominator together where it was reached, and the denominator alone where
210
+ * it was skipped. On a library built from the starter primitives this is
211
+ * nought (0223); on one built from a deployment's own it is most of the rows,
212
+ * and that is the thinness the server-side join already names rather than a
213
+ * fault here (0212).
214
+ */
215
+ readonly floored: number;
216
+ /**
217
+ * Time on screen across its placements, added.
218
+ *
219
+ * A volume of attention and **not a duration anybody spent**: a part is on
220
+ * screen while its children are, so a nested placement's seconds are its
221
+ * ancestors' too. Comparable between two kinds of the same depth and
222
+ * meaningless added across kinds, which is why nothing here adds it.
223
+ */
224
+ readonly dwellMs: number;
225
+ /** Presses, filed against the part the reader used, so no press is in two rows (0167). */
226
+ readonly activations: number;
227
+ readonly opens: number;
228
+ readonly closes: number;
229
+ /** Forms this kind of part let go (0211). */
230
+ readonly completions: number;
231
+ };
232
+ /** What a deployment's library does for its readers, by kind of part. */
233
+ export type LibraryReading = {
234
+ /**
235
+ * Every type that stands anywhere, most placements skipped first.
236
+ *
237
+ * Then the lower read share, then by type, so two kinds that are skipped
238
+ * equally often do not reorder on a refresh.
239
+ */
240
+ readonly byType: readonly KindReading[];
241
+ /**
242
+ * Every role in the vocabulary that stands anywhere, then the row for parts
243
+ * whose type declared none, in the same order as {@link byType}.
244
+ *
245
+ * Thin today for the reason every role figure in this subsystem is thin:
246
+ * nothing in `src/primitives/` declares one, so nearly every part is in the
247
+ * `null` row. The join is at read time (0212), so the day a role is declared
248
+ * every counter already stored reinterprets and these rows start answering
249
+ * without a migration.
250
+ */
251
+ readonly byRole: readonly KindReading[];
252
+ /** Readings counted, which is revisions of pages and not trees. */
253
+ readonly pages: number;
254
+ /** Distinct trees across them. */
255
+ readonly trees: number;
256
+ /** Element nodes across them, which is the sum of every type row's placements. */
257
+ readonly placements: number;
258
+ /** Placements by standing, over the whole library. */
259
+ readonly standings: Readonly<Record<PartStanding, number>>;
260
+ /**
261
+ * The type skipped in the most places, which is the kind to look at first.
262
+ *
263
+ * By the **count** of places and not by the share, for the reason a page's
264
+ * falls are ranked by the readers they lose (0221): a kind skipped in its one
265
+ * and only place is a perfect share and a smaller problem than one skipped in
266
+ * seven of nine. `null` where nothing anywhere was skipped — a healthy
267
+ * deployment and an unmeasured one both, which {@link standings} tells apart.
268
+ *
269
+ * A type and never a role, because a type is the thing an author can replace.
270
+ */
271
+ readonly mostSkipped: KindReading | null;
272
+ /** The type used most, by presses. A count of things that happened, not of readers. */
273
+ readonly mostUsed: KindReading | null;
274
+ /**
275
+ * Readings of a revision beyond the first, which were dropped.
276
+ *
277
+ * A caller that concatenated two reads holds one page twice, and a page twice
278
+ * in a census is the one way a census can lie about how much of a library
279
+ * there is.
280
+ */
281
+ readonly duplicated: number;
282
+ /**
283
+ * Types whose readings disagreed about the role they play, where the first
284
+ * reading's answer stands.
285
+ *
286
+ * The one failure this join can have that nothing else would catch: readings
287
+ * joined against two different registries, concatenated. A type plays one part
288
+ * (0114), so a disagreement is not a fact about the library — it is two
289
+ * libraries read as one, and every role row below is then about neither.
290
+ */
291
+ readonly roleDisagreed: readonly PrimitiveType[];
292
+ };
293
+ /**
294
+ * Whether a kind of part gets read, across every page it stands on.
295
+ *
296
+ * Takes the readings rather than the counters and the trees, for the reason
297
+ * every derived reading in this subsystem does: the standings and the words are
298
+ * what this is made of, and deriving them twice is how two screens come to
299
+ * disagree. A caller with a window of counters reads each page, then this.
300
+ *
301
+ * Linear in the parts handed in, with one pass that fills both groupings: a pass
302
+ * per key would be a walk of the whole library per member of the role
303
+ * vocabulary, and the vocabulary grows while the library is what it is.
304
+ */
305
+ export declare const libraryReadingOf: (readings: readonly PageReading[]) => LibraryReading;
306
+ //# sourceMappingURL=library.d.ts.map
@@ -0,0 +1,178 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { PRIMITIVE_ROLES } from "../role.js";
3
+ import { readingKeyOf } from "./audiences.js";
4
+ import { PART_STANDINGS } from "./parts.js";
5
+ import { countWords } from "./words.js";
6
+ export const KIND_SILENCES = everyMemberOf()([
7
+ "unread",
8
+ "unplaced",
9
+ ]);
10
+ /** One line per silence, for a surface saying why a kind has no share. */
11
+ export const describeKindSilence = (silence) => {
12
+ switch (silence) {
13
+ case "unread":
14
+ return "nothing reported a view of any place this kind of part stands";
15
+ case "unplaced":
16
+ return "nothing in the pages read is of this kind";
17
+ }
18
+ };
19
+ /** A key as a string, for a surface keying a list and for this module's own grouping. */
20
+ export const kindKeyOf = (kind) => kind.by === "type" ? `type\u0000${kind.type}` : `role\u0000${kind.role ?? ""}`;
21
+ const NO_STANDINGS = Object.freeze(Object.fromEntries(PART_STANDINGS.map((standing) => [standing, 0])));
22
+ const tallying = (kind) => ({
23
+ kind,
24
+ role: null,
25
+ placements: 0,
26
+ trees: new Set(),
27
+ revisions: new Set(),
28
+ standings: { ...NO_STANDINGS },
29
+ words: 0,
30
+ wordsReached: 0,
31
+ floored: 0,
32
+ dwellMs: 0,
33
+ activations: 0,
34
+ opens: 0,
35
+ closes: 0,
36
+ completions: 0,
37
+ });
38
+ const add = (into, part, page, revision) => {
39
+ const words = countWords(part.copy.words);
40
+ into.placements += 1;
41
+ into.trees.add(page.treeId);
42
+ into.revisions.add(revision);
43
+ into.standings[part.standing] += 1;
44
+ into.words += words;
45
+ into.wordsReached += part.standing === "read" ? words : 0;
46
+ into.floored += part.copy.unread.length > 0 || part.copy.unspoken.length > 0 ? 1 : 0;
47
+ into.dwellMs += part.counters?.dwellMs ?? 0;
48
+ into.activations += part.counters?.activations ?? 0;
49
+ into.opens += part.counters?.opens ?? 0;
50
+ into.closes += part.counters?.closes ?? 0;
51
+ into.completions += part.counters?.completions ?? 0;
52
+ };
53
+ /**
54
+ * The silence, with the two reasons tried in the order they have to be tried in.
55
+ *
56
+ * Nothing of the kind before nothing measured, because *there is no such part in
57
+ * this library* is a better answer than *nobody was seen reading it*, and the
58
+ * second is true of the first by accident.
59
+ */
60
+ const silenceOf = (of, verdicts) => {
61
+ if (of.placements === 0)
62
+ return "unplaced";
63
+ return verdicts === 0 ? "unread" : null;
64
+ };
65
+ const rowOf = (of) => {
66
+ const verdicts = of.standings.read + of.standings.skipped;
67
+ return {
68
+ kind: of.kind,
69
+ role: of.kind.by === "type" ? of.role : null,
70
+ placements: of.placements,
71
+ trees: of.trees.size,
72
+ revisions: of.revisions.size,
73
+ standings: { ...of.standings },
74
+ readShare: verdicts === 0 ? null : of.standings.read / verdicts,
75
+ silence: silenceOf(of, verdicts),
76
+ words: of.words,
77
+ wordsReached: of.wordsReached,
78
+ wordShare: of.words === 0 ? null : of.wordsReached / of.words,
79
+ floored: of.floored,
80
+ dwellMs: of.dwellMs,
81
+ activations: of.activations,
82
+ opens: of.opens,
83
+ closes: of.closes,
84
+ completions: of.completions,
85
+ };
86
+ };
87
+ /** The name a row is ordered by, which is the key's own and never the row's position. */
88
+ const nameOf = (kind) => (kind.by === "type" ? kind.type : (kind.role ?? ""));
89
+ /**
90
+ * The kind to look at first, which is the ranking rule spelled once.
91
+ *
92
+ * Most places skipped, then the lower read share, then by name — so a kind with
93
+ * no share at all sorts after one with a share of nought rather than above it,
94
+ * because `null` is *nothing can be said* and not *nobody read it*.
95
+ */
96
+ const worseOf = (one, other) => other.standings.skipped - one.standings.skipped ||
97
+ (one.readShare ?? 2) - (other.readShare ?? 2) ||
98
+ nameOf(one.kind).localeCompare(nameOf(other.kind));
99
+ /**
100
+ * Whether a kind of part gets read, across every page it stands on.
101
+ *
102
+ * Takes the readings rather than the counters and the trees, for the reason
103
+ * every derived reading in this subsystem does: the standings and the words are
104
+ * what this is made of, and deriving them twice is how two screens come to
105
+ * disagree. A caller with a window of counters reads each page, then this.
106
+ *
107
+ * Linear in the parts handed in, with one pass that fills both groupings: a pass
108
+ * per key would be a walk of the whole library per member of the role
109
+ * vocabulary, and the vocabulary grows while the library is what it is.
110
+ */
111
+ export const libraryReadingOf = (readings) => {
112
+ const rows = new Map();
113
+ const seen = new Set();
114
+ const trees = new Set();
115
+ const standings = { ...NO_STANDINGS };
116
+ const disagreed = new Set();
117
+ let pages = 0;
118
+ let duplicated = 0;
119
+ let placements = 0;
120
+ /**
121
+ * Every role in the vocabulary gets a row whether or not anything plays it,
122
+ * the way a page's role rows do — a role nothing in the library plays is a
123
+ * fact about the library worth having, and a surface that had to tell a
124
+ * missing row from an empty one would be reading the vocabulary itself.
125
+ */
126
+ for (const role of [...PRIMITIVE_ROLES, null]) {
127
+ const kind = { by: "role", role };
128
+ rows.set(kindKeyOf(kind), tallying(kind));
129
+ }
130
+ for (const reading of readings) {
131
+ const revision = readingKeyOf(reading);
132
+ if (seen.has(revision)) {
133
+ duplicated += 1;
134
+ continue;
135
+ }
136
+ seen.add(revision);
137
+ trees.add(reading.treeId);
138
+ pages += 1;
139
+ for (const part of reading.parts) {
140
+ const keys = [
141
+ { by: "type", type: part.type },
142
+ { by: "role", role: part.role },
143
+ ];
144
+ placements += 1;
145
+ standings[part.standing] += 1;
146
+ for (const kind of keys) {
147
+ const key = kindKeyOf(kind);
148
+ const row = rows.get(key) ?? tallying(kind);
149
+ if (kind.by === "type") {
150
+ if (row.placements === 0)
151
+ row.role = part.role;
152
+ else if (row.role !== part.role)
153
+ disagreed.add(part.type);
154
+ }
155
+ add(row, part, reading, revision);
156
+ rows.set(key, row);
157
+ }
158
+ }
159
+ }
160
+ const built = [...rows.values()].map(rowOf);
161
+ const byType = built.filter((row) => row.kind.by === "type").sort(worseOf);
162
+ return {
163
+ byType,
164
+ byRole: built.filter((row) => row.kind.by === "role").sort(worseOf),
165
+ pages,
166
+ trees: trees.size,
167
+ placements,
168
+ standings,
169
+ mostSkipped: byType.find((row) => row.standings.skipped > 0) ?? null,
170
+ mostUsed: byType
171
+ .filter((row) => row.activations > 0)
172
+ .sort((one, other) => other.activations - one.activations ||
173
+ nameOf(one.kind).localeCompare(nameOf(other.kind)))[0] ?? null,
174
+ duplicated,
175
+ roleDisagreed: [...disagreed].sort((one, other) => one.localeCompare(other)),
176
+ };
177
+ };
178
+ //# sourceMappingURL=library.js.map
@@ -1,5 +1,6 @@
1
1
  import { type Clock } from "../runtime/events.js";
2
2
  import { type ReaderSignalJournal } from "./journal.js";
3
+ import type { ReaderRegionStore } from "./region.js";
3
4
  import type { ReaderTallyStore } from "./tally.js";
4
5
  /**
5
6
  * The buffer and the counters, in the process.
@@ -14,4 +15,12 @@ import type { ReaderTallyStore } from "./tally.js";
14
15
  */
15
16
  export declare const memoryReaderSignalJournal: (clock?: Clock) => ReaderSignalJournal;
16
17
  export declare const memoryReaderTallyStore: () => ReaderTallyStore;
18
+ /**
19
+ * Where readers were, in the process.
20
+ *
21
+ * Additive like the tallies, and for a sharper reason: every call is one
22
+ * delivery's worth of arrivals, so a store that replaced would report the last
23
+ * reader rather than the readership.
24
+ */
25
+ export declare const memoryReaderRegionStore: () => ReaderRegionStore;
17
26
  //# sourceMappingURL=memory.d.ts.map