@jam-overture/loom 0.1.0 → 0.2.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 (290) 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/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -0,0 +1,319 @@
1
+ import type { PrimitiveType } from "../primitive-type.js";
2
+ import { type PrimitiveRole } from "../role.js";
3
+ import { type KindKey, type KindSilence } from "./library.js";
4
+ import { type UnscaledPage } from "./library-reach.js";
5
+ import { type PaceSilence, type PaceStanding } from "./pace.js";
6
+ import { type StoredPageViews } from "./page-views.js";
7
+ import type { PageReading } from "./parts.js";
8
+ /**
9
+ * Whether the readers who meet a kind of part have time for what it says.
10
+ *
11
+ * Four readings already stand on one list of `PageReading`s and answer four
12
+ * different questions about one primitive type: the **places** it stands and
13
+ * how many were reached ([`library.ts`](library.ts), 0257), the share of the
14
+ * **readers** who met those places that read it
15
+ * ([`library-reach.ts`](library-reach.ts), 0256), the share of those readers
16
+ * that acted inside it ([`library-action.ts`](library-action.ts), 0265), and
17
+ * what a change did to each of those.
18
+ *
19
+ * **Every one of them is about reach, and none of them is about reading.** A
20
+ * part counts as reached when half of it was half a viewport's height up the
21
+ * screen (0136), which is a fact about scrolling and not about a reader. The
22
+ * question an author rewriting a band actually has is the next one — *did
23
+ * anybody have time to read it* — and a page's own reading has answered it per
24
+ * part since [`pace.ts`](pace.ts) landed: the time its readers had, against the
25
+ * time its words take at a costing rate. **Asked of a kind it was unaskable**,
26
+ * for the reason every library question was before the join that answers it: a
27
+ * type's placements are scattered across forty readings and nothing added them
28
+ * up.
29
+ *
30
+ * This is that join. It is the **twenty-second** thing taken out of what this
31
+ * subsystem already knows rather than collected: no payload, no browser change,
32
+ * no counter that does not exist, no column and no byte on any wire.
33
+ *
34
+ * ## The figure is a pooled ratio and not a mean of ratios
35
+ *
36
+ * Each placement contributes two reader-milliseconds figures and the kind's
37
+ * pace is the quotient of the two sums:
38
+ *
39
+ * - **the time on screen**, `dwellMs`, added exactly as the rows hold it. It is
40
+ * already summed over the readers who were there, so it needs no weight;
41
+ * - **the time its words take those readers**, `readers × wordsWithin ×
42
+ * msPerWord`, with the readers put on the door's scale by `atDoorScale`
43
+ * before two pages are added together (0250).
44
+ *
45
+ * What comes out is a mean of the per-placement paces **weighted by the words
46
+ * each placement put in front of readers**, which is the ranking key a page's
47
+ * own reading already orders its parts by (0221, applied to pace): a caption
48
+ * two readers hurried past is a worse ratio and a smaller thing than a band
49
+ * four hundred of them did, and a mean of ratios would let the caption drown
50
+ * the band.
51
+ *
52
+ * The straddle correction divides out of the numerator exactly: a page view
53
+ * counted twice by a rollup carries one page view's dwell, so `dwellMs` is
54
+ * sound as it stands and the whole of the correction is in the readers. That is
55
+ * the same cancellation 0229 relies on one level down, arrived at here rather
56
+ * than assumed.
57
+ *
58
+ * ## A page the door cannot scale is kept, and that is the opposite of 0256
59
+ *
60
+ * A kind's share of readers is withheld entirely where one bearing page has no
61
+ * door row, because a weighted mean over the pages that could be priced is a
62
+ * figure whose denominator nobody named. **This reading keeps the page and
63
+ * applies no correction to it**, and the difference is which way the missing
64
+ * correction moves the claim.
65
+ *
66
+ * The correction only ever makes the readers fewer, so leaving it off only ever
67
+ * makes the denominator bigger and the pace lower — **towards `skimmed`, which
68
+ * is this module's safe verdict** and the one it is built to be able to defend
69
+ * (see `pace.ts` on why `skimmed` is reached before the floor is consulted). A
70
+ * share of readers has no safe direction, so it must refuse; a pace has one, so
71
+ * it may answer and say how much of its evidence was uncorrected.
72
+ * {@link KindPace.unscaled} is that figure and {@link LibraryPace.unscaled}
73
+ * names the pages, in the vocabulary whose subject is a page (0240).
74
+ *
75
+ * ## A placement inside another of its own kind is counted once
76
+ *
77
+ * A part is judged against its **subtree's** words, because the words on screen
78
+ * while a band was up are the band's and its children's — so a kind's figures
79
+ * nest wherever it stands inside itself. A stack inside a stack would put the
80
+ * inner stack's words and the inner stack's seconds into the type row twice,
81
+ * and the role row for parts that declare none is nearly every part of nearly
82
+ * every page, so without a rule it would count a page's words once per level.
83
+ *
84
+ * So **the outermost placement of a kind on a page stands for the ones inside
85
+ * it**: an inner placement is counted in {@link KindPace.nested} and is in no
86
+ * term. Nothing is lost by it — the outer placement's words already include the
87
+ * inner one's — and what it buys is the one property that makes the figure
88
+ * addable at all (0158).
89
+ *
90
+ * ## What is deliberately not published
91
+ *
92
+ * **No library-wide pace.** Two kinds nest in each other wherever a band holds
93
+ * a paragraph, so a total over the kinds adds one page's words once per level
94
+ * of its tree — the artefact a census of places does not have and the reason
95
+ * `library.ts` refuses to add `dwellMs` across kinds. Every figure here is a
96
+ * row's, and the only error available to it is one page standing in it twice,
97
+ * which is the one thing deduplicated.
98
+ *
99
+ * **Nothing the other four readings say.** The standings, the places, the
100
+ * words, the uses and the shares stay where they are and pair on
101
+ * {@link kindKeyOf}.
102
+ *
103
+ * Pure. It reaches no store, no clock and no DOM, it is linear in the parts of
104
+ * the readings times the rows handed in, and nothing in it survives into a
105
+ * browser bundle.
106
+ */
107
+ /** Why a kind of part has no pace. */
108
+ export type KindPaceSilence =
109
+ /**
110
+ * The census's own two reasons, which were already a kind's and are reused as
111
+ * values rather than said again (0256).
112
+ *
113
+ * `unread` here is *no place this kind stands reported a view*, which is what
114
+ * a page's own reading calls `unreached` at a part.
115
+ */
116
+ KindSilence
117
+ /**
118
+ * Nothing countable is said anywhere it stands that readers reached, and
119
+ * something in it declares no `copy` (0122).
120
+ *
121
+ * The same state as a part's `unreadable`, at a kind — and **also** the state
122
+ * of a kind whose pace was computed and is not low enough to be safe: words
123
+ * nobody counted can only make a part more skimmed, so `skimmed` stands and
124
+ * anything above it is a claim resting on a floor. That is `paceStandingOf`'s
125
+ * asymmetry, unchanged, and {@link KindPace.floored} says how many placements
126
+ * caused it.
127
+ */
128
+ | "unreadable"
129
+ /**
130
+ * It says nothing that takes time to read, anywhere it stands, and nothing
131
+ * went uncounted either.
132
+ *
133
+ * A spacer, a rule, a stack that only holds other parts. Kept apart from
134
+ * `unreadable` because *there are none* and *nobody said* are different
135
+ * answers (0122).
136
+ */
137
+ | "wordless";
138
+ export declare const KIND_PACE_SILENCES: readonly KindPaceSilence[];
139
+ /** One line per silence, for a surface saying why a kind has no pace. */
140
+ export declare const describeKindPaceSilence: (silence: KindPaceSilence) => string;
141
+ /** One kind of part, against the time its readers had for what it says. */
142
+ export type KindPace = {
143
+ readonly kind: KindKey;
144
+ /** What part a type plays (0114), or `null`. Always `null` on a role row, which carries it as its key. */
145
+ readonly role: PrimitiveRole | null;
146
+ /** Element nodes of this kind across the readings, as the census counts them. */
147
+ readonly placements: number;
148
+ /**
149
+ * Placements standing inside another placement of the same kind, which are in
150
+ * no term here.
151
+ *
152
+ * The outer one's words and seconds already include theirs. Nought on most
153
+ * type rows and the ordinary state of a role row, because a page's parts
154
+ * nearly all declare no role and so are all one kind.
155
+ */
156
+ readonly nested: number;
157
+ /** Placements in the figures: not nested, reached, and saying something counted. */
158
+ readonly counted: number;
159
+ /** Why the rest have no pace of their own. The counts add to `placements − nested − counted`. */
160
+ readonly silences: Readonly<Record<PaceSilence, number>>;
161
+ /**
162
+ * Every placement a page could be read for, by its own verdict.
163
+ *
164
+ * The census view of the same set the two figures above partition: the counts
165
+ * add to `placements − nested`, and `unknown` is a placement with no pace of
166
+ * its own *or* one whose words are a floor.
167
+ */
168
+ readonly standings: Readonly<Record<PaceStanding, number>>;
169
+ /** Revisions bearing a counted placement. */
170
+ readonly pages: number;
171
+ /** Counted placements whose words are a floor, because a type in them declares no `copy` (0122). */
172
+ readonly floored: number;
173
+ /**
174
+ * Counted placements that are a page's root, which is why a kind holding the
175
+ * whole page is out of {@link LibraryPace.mostSkimmed}.
176
+ *
177
+ * By words it would win every ranking it was entered in, for the reason a
178
+ * page's own reading keeps its root out of `mostSkimmed`: the page contains
179
+ * every part.
180
+ */
181
+ readonly whole: number;
182
+ /**
183
+ * Page views that reached a counted placement, at the door's scale, counted
184
+ * once per place it stands.
185
+ *
186
+ * **Not a count of people and deliberately not rounded into one** (0256): it
187
+ * is a weight, and a reader who met three placements of one kind is three of
188
+ * them. `null` under a silence.
189
+ */
190
+ readonly readers: number | null;
191
+ /**
192
+ * Time on screen across the counted placements, added, exactly as the rows
193
+ * hold it.
194
+ *
195
+ * Sound without a correction: a page view a rollup counted twice carries one
196
+ * page view's dwell. **Nests across kinds** — a band's seconds are its
197
+ * paragraph's too — so it is never added across rows.
198
+ */
199
+ readonly dwellMs: number;
200
+ /**
201
+ * The time its words take the readers who met it: `readers × wordsWithin ×
202
+ * msPerWord`, added over the counted placements.
203
+ *
204
+ * The denominator, in the same reader-milliseconds {@link dwellMs} is in.
205
+ * `null` under a silence.
206
+ */
207
+ readonly needMs: number | null;
208
+ /** `dwellMs ÷ readers`: the time the typical reader who met a place of it had there. `null` under a silence. */
209
+ readonly spentMs: number | null;
210
+ /**
211
+ * `needMs − dwellMs` where positive: the reading time its readers did not
212
+ * have, and the key the rows are ordered by.
213
+ *
214
+ * By the **amount** and not by the ratio, for the reason a deployment's falls
215
+ * are ordered by the readers they lose (0221). Nought where readers had time
216
+ * enough, and `null` under a silence.
217
+ */
218
+ readonly shortMs: number | null;
219
+ /** `dwellMs ÷ needMs`. `1` is exactly time enough. `null` under a silence. */
220
+ readonly pace: number | null;
221
+ /** The verdict, by `paceStandingOf` — so a floor can hold up anything but `skimmed`. */
222
+ readonly standing: PaceStanding;
223
+ /**
224
+ * Of {@link readers}, those on a page the door could not scale, so no
225
+ * straddle correction was applied to them.
226
+ *
227
+ * It biases the pace **down**, towards `skimmed`, which is why the row is
228
+ * published rather than withheld. `LibraryPace.unscaled` names the pages.
229
+ */
230
+ readonly unscaled: number;
231
+ readonly silence: KindPaceSilence | null;
232
+ };
233
+ /** What a deployment's library asks of its readers' time, by kind of part. */
234
+ export type LibraryPace = {
235
+ /**
236
+ * Every type that stands anywhere, most reading time missing first.
237
+ *
238
+ * Then the lower pace, then by type, so two kinds that ask the same do not
239
+ * reorder on a refresh. A kind with no pace sorts after one whose pace is
240
+ * nought, because `null` is *nothing can be said* and not *nobody had any
241
+ * time for it*.
242
+ */
243
+ readonly byType: readonly KindPace[];
244
+ /** Every role in the vocabulary, then the row for parts whose type declared none, in the same order. */
245
+ readonly byRole: readonly KindPace[];
246
+ /** Readings counted, which is revisions of pages and not trees. */
247
+ readonly pages: number;
248
+ /** Distinct trees across them. */
249
+ readonly trees: number;
250
+ /** Element nodes across them, which is the sum of every type row's placements. */
251
+ readonly placements: number;
252
+ /** Placements standing inside another of their own type, across the type rows. */
253
+ readonly nested: number;
254
+ /** Pages whose door could scale them, which is where the correction comes from. */
255
+ readonly scaled: number;
256
+ /**
257
+ * The pages bearing a counted placement that the door could not scale, by
258
+ * tree and newest revision first.
259
+ *
260
+ * The actionable half of every {@link KindPace.unscaled} above: one of these
261
+ * pages is why. Empty is the healthy state, and a page here still has every
262
+ * figure it contributed to — see the module documentation on why this reading
263
+ * keeps it where a share of readers refuses it.
264
+ */
265
+ readonly unscaled: readonly UnscaledPage[];
266
+ /**
267
+ * The type whose readers are shortest of the time its words take, which is
268
+ * the kind to rewrite first.
269
+ *
270
+ * By {@link KindPace.shortMs} and never by the ratio, and **never a kind that
271
+ * holds a page's root**, for the reason a page's own reading keeps its root
272
+ * out of the same ranking. A type and never a role, because a type is the
273
+ * thing an author can replace.
274
+ */
275
+ readonly mostSkimmed: KindPace | null;
276
+ /**
277
+ * Readings of a revision beyond the first, which were dropped.
278
+ *
279
+ * A caller that concatenated two reads holds one page twice, and a page twice
280
+ * doubles both terms of every ratio here while looking like twice the
281
+ * evidence.
282
+ */
283
+ readonly duplicated: number;
284
+ /** Door rows for one revision beyond the first, which were ignored. */
285
+ readonly duplicatedRows: number;
286
+ /**
287
+ * Types whose readings disagreed about the role they play, where the first
288
+ * reading's answer stands.
289
+ *
290
+ * Raised here rather than fetched from the census, because every role row
291
+ * below is about neither library when it is set. Detected off the same
292
+ * readings by the same rule as the other library readings, so they cannot
293
+ * disagree about it.
294
+ */
295
+ readonly roleDisagreed: readonly PrimitiveType[];
296
+ /** The costing rate that was applied, which is the default unless one was given. */
297
+ readonly wordsPerMinute: number;
298
+ };
299
+ export type LibraryPaceOptions = {
300
+ /**
301
+ * The costing rate, where {@link READING_WORDS_PER_MINUTE} is wrong for this
302
+ * deployment's text. Refused the way a page's own reading refuses it.
303
+ */
304
+ readonly wordsPerMinute?: number;
305
+ };
306
+ /**
307
+ * Whether the readers who meet a kind of part have time for what it says.
308
+ *
309
+ * Takes the readings and the whole window of page-view rows a deployment holds
310
+ * — each page's own row is picked out of them by the published matching rule
311
+ * (`pageViewsFor`) rather than by a hand-written copy of it, because the
312
+ * pairing is the part of every join here that fails quietly when it is got
313
+ * wrong.
314
+ *
315
+ * Linear in the parts of the readings times the rows, with one pass that fills
316
+ * both groupings.
317
+ */
318
+ export declare const libraryPaceOf: (readings: readonly PageReading[], rows: readonly StoredPageViews[], options?: LibraryPaceOptions) => LibraryPace;
319
+ //# sourceMappingURL=library-pace.d.ts.map
@@ -0,0 +1,305 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { PRIMITIVE_ROLES } from "../role.js";
3
+ import { readingKeyOf } from "./audiences.js";
4
+ import { atDoorScale, doorOf } from "./door.js";
5
+ import { kindKeyOf } from "./library.js";
6
+ import {} from "./library-reach.js";
7
+ import { paceStandingOf, readingPaceOf, READING_WORDS_PER_MINUTE, } from "./pace.js";
8
+ import { pageViewsFor } from "./page-views.js";
9
+ export const KIND_PACE_SILENCES = everyMemberOf()([
10
+ "unread",
11
+ "unplaced",
12
+ "unreadable",
13
+ "wordless",
14
+ ]);
15
+ /** One line per silence, for a surface saying why a kind has no pace. */
16
+ export const describeKindPaceSilence = (silence) => {
17
+ switch (silence) {
18
+ case "unread":
19
+ return "nothing reported a view of any place this kind of part stands";
20
+ case "unplaced":
21
+ return "nothing in the pages read is of this kind";
22
+ case "unreadable":
23
+ return "some of its words could not be counted, so only a skim could be claimed of it";
24
+ case "wordless":
25
+ return "it says nothing that takes time to read";
26
+ }
27
+ };
28
+ /**
29
+ * **There is no `inflation` option**, and that is the one place this reading's
30
+ * arguments differ from a page's.
31
+ *
32
+ * A page's reading takes the straddle correction as a number because it is
33
+ * about one page and the caller holds that page's row. A library spans forty of
34
+ * them, each with its own straddle rate (0250), and one scalar over all of them
35
+ * would be a correction nobody measured. So the rows are handed in instead and
36
+ * each page's own `inflation` is read off its own door, which is the same
37
+ * argument that put the rows in `libraryReachOf`'s signature.
38
+ */
39
+ const NO_STANDINGS = Object.freeze({
40
+ skimmed: 0,
41
+ paced: 0,
42
+ lingered: 0,
43
+ unknown: 0,
44
+ });
45
+ const NO_SILENCES = Object.freeze({
46
+ unreached: 0,
47
+ unreadable: 0,
48
+ wordless: 0,
49
+ });
50
+ const tallying = (kind) => ({
51
+ kind,
52
+ role: null,
53
+ placements: 0,
54
+ nested: 0,
55
+ counted: 0,
56
+ floored: 0,
57
+ whole: 0,
58
+ standings: { ...NO_STANDINGS },
59
+ silences: { ...NO_SILENCES },
60
+ pages: new Set(),
61
+ readers: 0,
62
+ dwellMs: 0,
63
+ needMs: 0,
64
+ unscaled: 0,
65
+ });
66
+ /**
67
+ * One placement's contribution.
68
+ *
69
+ * A nested placement is counted and returns: the outer one standing for it is
70
+ * the whole of the rule, and letting it through would be the one error here
71
+ * that cannot be undone afterwards (0158).
72
+ */
73
+ const add = (into, part, nested, door, msPerWord, revision) => {
74
+ into.placements += 1;
75
+ if (nested) {
76
+ into.nested += 1;
77
+ return;
78
+ }
79
+ into.standings[part.standing] += 1;
80
+ if (part.pace === null) {
81
+ /**
82
+ * A part with no pace always carries the reason it has none, because
83
+ * `pace.ts` fills the silence for every standing of `unknown` and a part
84
+ * with no pace is always one. The fallback is the type system's and not a
85
+ * state.
86
+ */
87
+ into.silences[part.silence ?? "unreached"] += 1;
88
+ return;
89
+ }
90
+ const readers = door.silence === null ? atDoorScale(part.readers, door) : part.readers;
91
+ into.counted += 1;
92
+ into.pages.add(revision);
93
+ into.floored += part.floored ? 1 : 0;
94
+ into.whole += part.depth === 0 ? 1 : 0;
95
+ into.readers += readers;
96
+ into.dwellMs += part.dwellMs;
97
+ into.needMs += readers * part.wordsWithin * msPerWord;
98
+ into.unscaled += door.silence === null ? 0 : readers;
99
+ };
100
+ /**
101
+ * The silence, with the reasons tried in the order they have to be tried in.
102
+ *
103
+ * Nothing of the kind before nothing read, because *there is none of it* is a
104
+ * better answer than *nobody was seen reading it* and the second is true of the
105
+ * first by accident. Then the part-level reasons, in the order a part's own
106
+ * reading reaches them: no reader before no words, and a floor before silence,
107
+ * because *nobody counted them* outranks *there are none*.
108
+ */
109
+ const silenceOf = (of, standing) => {
110
+ if (of.placements === 0)
111
+ return "unplaced";
112
+ if (of.counted === 0) {
113
+ if (of.silences.unreadable > 0)
114
+ return "unreadable";
115
+ if (of.silences.wordless > 0)
116
+ return "wordless";
117
+ return "unread";
118
+ }
119
+ return standing === "unknown" ? "unreadable" : null;
120
+ };
121
+ const rowOf = (of) => {
122
+ /**
123
+ * A counted placement always has a reader and a word, so a kind with one has
124
+ * a denominator: `needMs` is nought exactly when `counted` is.
125
+ */
126
+ const pace = of.counted === 0 ? null : of.dwellMs / of.needMs;
127
+ const standing = paceStandingOf(pace, of.floored > 0);
128
+ const silence = silenceOf(of, standing);
129
+ const measured = silence === null;
130
+ return {
131
+ kind: of.kind,
132
+ role: of.kind.by === "type" ? of.role : null,
133
+ placements: of.placements,
134
+ nested: of.nested,
135
+ counted: of.counted,
136
+ silences: { ...of.silences },
137
+ standings: { ...of.standings },
138
+ pages: of.pages.size,
139
+ floored: of.floored,
140
+ whole: of.whole,
141
+ readers: measured ? of.readers : null,
142
+ dwellMs: of.dwellMs,
143
+ needMs: measured ? of.needMs : null,
144
+ spentMs: measured ? of.dwellMs / of.readers : null,
145
+ shortMs: measured ? Math.max(0, of.needMs - of.dwellMs) : null,
146
+ pace: measured ? pace : null,
147
+ standing,
148
+ unscaled: of.unscaled,
149
+ silence,
150
+ };
151
+ };
152
+ /** The name a row is ordered by, which is the key's own and never the row's position. */
153
+ const nameOf = (kind) => (kind.by === "type" ? kind.type : (kind.role ?? ""));
154
+ /**
155
+ * The worse of two, which is the ranking rule spelled once.
156
+ *
157
+ * Most reading time missing, then the lower pace, then by name — so a kind with
158
+ * no pace at all sorts after one whose pace is nought rather than above it.
159
+ */
160
+ const worseOf = (one, other) => (other.shortMs ?? -1) - (one.shortMs ?? -1) ||
161
+ (one.pace ?? Number.POSITIVE_INFINITY) - (other.pace ?? Number.POSITIVE_INFINITY) ||
162
+ nameOf(one.kind).localeCompare(nameOf(other.kind));
163
+ /** Tree id, then newest revision first, which is the order the page-view rows are read in. */
164
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) || other.revision - one.revision;
165
+ const MS_PER_MINUTE = 60_000;
166
+ /** A positive, finite option, or the fallback. Everything else is refused. */
167
+ const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
168
+ /**
169
+ * Whether the readers who meet a kind of part have time for what it says.
170
+ *
171
+ * Takes the readings and the whole window of page-view rows a deployment holds
172
+ * — each page's own row is picked out of them by the published matching rule
173
+ * (`pageViewsFor`) rather than by a hand-written copy of it, because the
174
+ * pairing is the part of every join here that fails quietly when it is got
175
+ * wrong.
176
+ *
177
+ * Linear in the parts of the readings times the rows, with one pass that fills
178
+ * both groupings.
179
+ */
180
+ export const libraryPaceOf = (readings, rows, options = {}) => {
181
+ const wordsPerMinute = positive(options.wordsPerMinute, READING_WORDS_PER_MINUTE);
182
+ const msPerWord = MS_PER_MINUTE / wordsPerMinute;
183
+ const tallies = new Map();
184
+ const seen = new Set();
185
+ const trees = new Set();
186
+ const unscaled = [];
187
+ const disagreed = new Set();
188
+ let pages = 0;
189
+ let placements = 0;
190
+ let nestedParts = 0;
191
+ let scaled = 0;
192
+ let duplicated = 0;
193
+ let duplicatedRows = 0;
194
+ /**
195
+ * Every role in the vocabulary gets a row whether or not anything plays it,
196
+ * the way the census's role rows do: a role nothing in the library plays is a
197
+ * fact about the library worth having, and a surface that had to tell a
198
+ * missing row from an empty one would be reading the vocabulary itself.
199
+ */
200
+ for (const role of [...PRIMITIVE_ROLES, null]) {
201
+ const kind = { by: "role", role };
202
+ tallies.set(kindKeyOf(kind), tallying(kind));
203
+ }
204
+ for (const reading of readings) {
205
+ const revision = readingKeyOf(reading);
206
+ if (seen.has(revision)) {
207
+ duplicated += 1;
208
+ continue;
209
+ }
210
+ seen.add(revision);
211
+ trees.add(reading.treeId);
212
+ pages += 1;
213
+ const found = pageViewsFor(reading, rows);
214
+ const door = doorOf(found.measured);
215
+ duplicatedRows += found.duplicated;
216
+ if (door.silence === null)
217
+ scaled += 1;
218
+ /**
219
+ * Each page's own straddle rate, off its own row (0250). A page the door
220
+ * cannot scale gets no correction, which leaves its pace low rather than
221
+ * high — see the module documentation on why that is answerable where a
222
+ * share of readers is not.
223
+ */
224
+ const paced = readingPaceOf(reading, {
225
+ inflation: found.measured?.inflation ?? 0,
226
+ wordsPerMinute,
227
+ });
228
+ /**
229
+ * How many placements of each kind are open above the part being read.
230
+ *
231
+ * The parts are pre-order with depths, so the open ancestors are what is
232
+ * left on the stack once everything at or below this depth has been closed
233
+ * — the same walk `pace.ts` totals subtrees with, and the reason it is
234
+ * depth rather than `parentId` is the same: a slot node is not a part and
235
+ * can hold element children, so the parent chain strands a whole band.
236
+ */
237
+ const open = [];
238
+ const openKinds = new Map();
239
+ let anyCounted = false;
240
+ const close = () => {
241
+ const frame = open.pop();
242
+ if (frame === undefined)
243
+ return;
244
+ for (const key of frame.keys)
245
+ openKinds.set(key, (openKinds.get(key) ?? 0) - 1);
246
+ };
247
+ for (const part of paced.parts) {
248
+ while ((open[open.length - 1]?.depth ?? -1) >= part.depth)
249
+ close();
250
+ const kinds = [
251
+ { by: "type", type: part.type },
252
+ { by: "role", role: part.role },
253
+ ];
254
+ const keys = kinds.map(kindKeyOf);
255
+ placements += 1;
256
+ kinds.forEach((kind, at) => {
257
+ const key = keys[at] ?? "";
258
+ const tally = tallies.get(key) ?? tallying(kind);
259
+ if (kind.by === "type") {
260
+ if (tally.placements === 0)
261
+ tally.role = part.role;
262
+ else if (tally.role !== part.role)
263
+ disagreed.add(part.type);
264
+ }
265
+ const nested = (openKinds.get(key) ?? 0) > 0;
266
+ if (kind.by === "type" && nested)
267
+ nestedParts += 1;
268
+ if (kind.by === "type" && !nested && part.pace !== null)
269
+ anyCounted = true;
270
+ add(tally, part, nested, door, msPerWord, revision);
271
+ tallies.set(key, tally);
272
+ });
273
+ open.push({ depth: part.depth, keys });
274
+ for (const key of keys)
275
+ openKinds.set(key, (openKinds.get(key) ?? 0) + 1);
276
+ }
277
+ /**
278
+ * A page the door cannot scale is listed only where something on it was
279
+ * counted: a page nobody read is not a page whose readers could not be
280
+ * scaled, and listing it would put the commonest healthy state on the one
281
+ * list here that is meant to be empty.
282
+ */
283
+ if (door.silence !== null && anyCounted) {
284
+ unscaled.push({ treeId: reading.treeId, revision: reading.revision, silence: door.silence });
285
+ }
286
+ }
287
+ const built = [...tallies.values()].map(rowOf);
288
+ const byType = built.filter((row) => row.kind.by === "type").sort(worseOf);
289
+ return {
290
+ byType,
291
+ byRole: built.filter((row) => row.kind.by === "role").sort(worseOf),
292
+ pages,
293
+ trees: trees.size,
294
+ placements,
295
+ nested: nestedParts,
296
+ scaled,
297
+ unscaled: [...unscaled].sort(byPage),
298
+ mostSkimmed: byType.find((row) => row.standing === "skimmed" && row.whole === 0) ?? null,
299
+ duplicated,
300
+ duplicatedRows,
301
+ roleDisagreed: [...disagreed].sort((one, other) => one.localeCompare(other)),
302
+ wordsPerMinute,
303
+ };
304
+ };
305
+ //# sourceMappingURL=library-pace.js.map