@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,377 @@
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 RevisionOf, type StoredPageViews } from "./page-views.js";
5
+ import type { PageReading } from "./parts.js";
6
+ import type { ReachSilence } from "./reach.js";
7
+ /**
8
+ * Of the readers who met a kind of part, the share that read it.
9
+ *
10
+ * [`library.ts`](library.ts) publishes a kind's standing as a share of the
11
+ * **places** it stands — *the testimonial band stands in nine places and
12
+ * readers reached two of them* — and is explicit that this is not a share of
13
+ * readers: a placement on a page nine thousand people read counts the same as
14
+ * one on a page three people read
15
+ * ([0257](../../decisions/0257-a-kind-of-part-is-read-across-the-places-it-stands-and-the-unit-is-the-placement.md)).
16
+ * The figure everybody asks for next is the other one, and this lane filed its
17
+ * shape the same morning rather than shipping a corrected number beside an
18
+ * uncorrected one on the same type.
19
+ *
20
+ * This is that figure. It is the **fifteenth** thing taken out of what this
21
+ * subsystem already knows rather than collected: no payload, no browser change,
22
+ * no counter that does not exist, no column and no byte on any wire.
23
+ *
24
+ * ## The unit is one page view of one place, and never a reader
25
+ *
26
+ * A reader cannot be the unit and no field would make them one. Two page views
27
+ * of two pages are two page views, with nothing that says whether one person
28
+ * made both — which is rule 1 of the plan and
29
+ * [0146](../../decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md),
30
+ * not a gap. So the unit is the pair *(a page view, a place this kind stands on
31
+ * that page)*: a page view of a page bearing three placements of one kind is
32
+ * three of them, which is what makes the figure addable at all.
33
+ *
34
+ * ## Each page's share is sound, and the weights are the door's
35
+ *
36
+ * A placement's share of its own page's readers is `reached ÷ appearances`,
37
+ * which is the estimate
38
+ * [0229](../../decisions/0229-a-share-of-readers-is-estimated-against-the-appearances-and-bounded-against-the-openings.md)
39
+ * settled: the straddle over-count is in both terms and very nearly divides
40
+ * out, because a reader who spanned two rollup windows spanned them for the
41
+ * whole page.
42
+ *
43
+ * **Across two pages it does not divide out, because the straddle rate is each
44
+ * page's own** — the fact that put every page's loss on the door's scale before
45
+ * an order over them could mean anything
46
+ * ([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)).
47
+ * A mean of the per-page shares weighted by `appearances` would weigh the pages
48
+ * readers linger on most heavily, so shortening a rollup window would move the
49
+ * figure and move no reader.
50
+ *
51
+ * So every term is put on the scale the door counts in, by 0250's correction
52
+ * and off that page's own row by the published matching rule:
53
+ *
54
+ * - the weight is `appearances ÷ (1 + inflation)`, which comes to
55
+ * `min(appearances, opened)` — the page views a rollup folded, at the door's
56
+ * scale. It is **taken as that minimum of two whole numbers**, because the
57
+ * division of three floats agrees with it to fifteen places and not to
58
+ * sixteen, and 0229 has already been bitten by exactly that;
59
+ * - the numerator is `reached × weight ÷ appearances`, so each page
60
+ * contributes its own sound share with that weight behind it.
61
+ *
62
+ * What comes out is `met ÷ counted`, and because the weights are counts of real
63
+ * page views rather than a projection onto arrivals nobody folded, **nothing
64
+ * here is withheld for a collection that is behind.** A page whose rollups are
65
+ * lagging weighs less than one that is caught up; that shifts the evidence and
66
+ * not the share, and {@link KindReach.pending} is the figure that says by how
67
+ * much.
68
+ *
69
+ * ## Two denominators, for 0229's reason one level up
70
+ *
71
+ * {@link KindReach.share} is taken of the folded page views at the door's
72
+ * scale, and {@link KindReach.atMost} of the openings, which are exact. The
73
+ * gap between them is the straddle and the lag together, and the identity
74
+ * `openings = counted + pending` is published rather than described.
75
+ *
76
+ * As in a page's own reading, the estimate may sit **above** the ceiling while
77
+ * openings are pending, because the two are then taken of different
78
+ * populations. That is not a contradiction and `pending` is the explanation.
79
+ *
80
+ * ## A kind standing on a page the door cannot scale has no share at all
81
+ *
82
+ * Not a share over the pages that could be scaled. A weighted mean over a
83
+ * subset is a figure whose denominator nobody named, and *of the places we
84
+ * could price* is not a sentence a surface will print — it will print the
85
+ * number. So the share is withheld for the whole kind, the reason is on the
86
+ * row, and the pages that caused it are published once for the reading with
87
+ * **their own** vocabulary's reason on them.
88
+ *
89
+ * Nothing is lost by the refusal: the census of places is sound on exactly the
90
+ * same readings, says so without a correction, and is one call away.
91
+ *
92
+ * ## What is deliberately not published
93
+ *
94
+ * **No reading-wide share.** A share over every kind at once is a share over
95
+ * every (page view, placement) pair in the deployment, in which a page with
96
+ * forty parts weighs forty times one with a single band — a number whose
97
+ * denominator is an artefact of how finely the pages were built. The artefact
98
+ * is a set of rows, so nothing is added across kinds and the only error
99
+ * available to it is one page standing in it twice, which is the one thing
100
+ * deduplicated here
101
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
102
+ *
103
+ * **No headcount.** `met` is a count of page views at the door's scale and is
104
+ * deliberately not rounded into people: a share of one part of a page
105
+ * multiplied back up was a count of readers larger than the page had, found on
106
+ * a reader card on 8 October, and a share of places times a readership is
107
+ * worse.
108
+ *
109
+ * **Nothing the census already says.** The standings, the words, the dwell and
110
+ * the occurrences are a kind's row in `library.ts` and are not restated here.
111
+ * The two readings are built from one list of readings and pair on
112
+ * {@link kindKeyOf}.
113
+ *
114
+ * Pure. It reaches no store, no clock and no DOM, it is linear in the parts of
115
+ * the readings times the rows handed in, and nothing in it survives into a
116
+ * browser bundle.
117
+ */
118
+ /**
119
+ * Why a kind has no share of the readers who met it.
120
+ *
121
+ * The census's own two reasons are **its values**, not two new spellings of
122
+ * them, so a surface drawing both readings of one kind prints one word for one
123
+ * state. The three added are the states of the door, said of a kind: each is
124
+ * caused by one page, and which page is
125
+ * {@link LibraryReach.unscaled}'s to say in the vocabulary whose subject is a
126
+ * page.
127
+ */
128
+ export type KindReachSilence = KindSilence
129
+ /**
130
+ * A page it stands on has no page-view row at the door, so no term of it can
131
+ * be put on a scale another page's shares could be added to.
132
+ *
133
+ * The page's own reading is as good as any other's and every figure in it
134
+ * stands; what is missing is the one number that makes two pages' shares
135
+ * comparable. Same state of the world as an order over pages calls
136
+ * `unscaled` and a page's own reading calls `unmeasured`, at a third subject.
137
+ */
138
+ | "unscaled"
139
+ /**
140
+ * A page it stands on has a row and nothing in it says a page view ever
141
+ * began.
142
+ *
143
+ * Kept apart from `unscaled` because the remedy is the opposite: a missing
144
+ * row is retention or an upgrade, and this is **senders that are not marking
145
+ * their openings** — every rate denominator-less while the counters look
146
+ * healthy, which is the diagnosis nothing else in this subsystem offers.
147
+ */
148
+ | "unopened"
149
+ /**
150
+ * A page it stands on has openings and no rollup has folded a window of them
151
+ * yet.
152
+ *
153
+ * The one reason here that resolves itself. It is what the first minutes of a
154
+ * deployment look like, and what a stalled collection looks like for ever.
155
+ */
156
+ | "uncounted";
157
+ export declare const KIND_REACH_SILENCES: readonly KindReachSilence[];
158
+ /** One line per silence, for a surface saying why a kind has no share of readers. */
159
+ export declare const describeKindReachSilence: (silence: KindReachSilence) => string;
160
+ /**
161
+ * One kind of part, against the readers who met the places it stands.
162
+ *
163
+ * Identity and the placement counts travel with the figures, so a surface
164
+ * drawing this never holds two lists side by side to find out how much is
165
+ * behind a share. Everything a census says about the kind — its standings, its
166
+ * words, its dwell, its uses — stays in the census and is paired on
167
+ * {@link kindKeyOf}.
168
+ */
169
+ export type KindReach = {
170
+ readonly kind: KindKey;
171
+ /** What part a type plays (0114), or `null`. Always `null` on a role row, which carries it as its key. */
172
+ readonly role: PrimitiveRole | null;
173
+ /** Element nodes of this kind across the readings, as the census counts them. */
174
+ readonly placements: number;
175
+ /**
176
+ * Placements a window could speak for, which are the ones in the figures.
177
+ *
178
+ * A placement whose standing is `unknown` is in a window that said nothing
179
+ * about it, and putting its nought into the numerator against its page's
180
+ * readers would call it a skip — which is the one direction a census of a
181
+ * quiet deployment must not be wrong in (0212). It is counted in
182
+ * {@link unknown} and is in no term here.
183
+ */
184
+ readonly verdicts: number;
185
+ /** Placements nothing could be said about, and therefore excluded. */
186
+ readonly unknown: number;
187
+ /** Revisions bearing at least one placement with a verdict. */
188
+ readonly pages: number;
189
+ /**
190
+ * Page views that began on a page bearing it, counted once per place it
191
+ * stands there. Exact (0219), and the denominator of {@link atMost}.
192
+ *
193
+ * `openings = counted + pending`, which is the identity the two denominators
194
+ * differ by.
195
+ */
196
+ readonly openings: number | null;
197
+ /**
198
+ * The same page views at the door's scale, keeping only those a rollup has
199
+ * folded: `appearances ÷ (1 + inflation)` per bearing page, which is
200
+ * `min(appearances, opened)`.
201
+ *
202
+ * The denominator of {@link share}. Not a projection — every page view in it
203
+ * was both counted at the door and folded into the counters the numerator
204
+ * comes from.
205
+ */
206
+ readonly counted: number | null;
207
+ /**
208
+ * Page views that reached a place this kind stands, at the door's scale.
209
+ *
210
+ * `reached × counted ÷ appearances`, added over the bearing placements. **Not
211
+ * a count of people and deliberately not rounded into one**: it is a reach
212
+ * stated at the door's scale, which is what makes two kinds' reach the same
213
+ * kind of number.
214
+ */
215
+ readonly met: number | null;
216
+ /** `counted − met`: the page views that met a page bearing it and did not reach the place. */
217
+ readonly missed: number | null;
218
+ /**
219
+ * `met ÷ counted` — the share of the readers who met it that read it.
220
+ *
221
+ * A weighted mean of each page's own sound share, with that page's exact
222
+ * arrivals behind it. It is above 1 exactly where {@link unreconciled} is
223
+ * non-nought and never otherwise.
224
+ *
225
+ * `null` where {@link silence} says why not.
226
+ */
227
+ readonly share: number | null;
228
+ /**
229
+ * The most the share could be: `min(reached, opened)` per bearing placement
230
+ * over the {@link openings}, never above 1.
231
+ *
232
+ * A ceiling rather than an estimate, for the reason a page's own reading
233
+ * bounds its shares (0229): no window boundary can inflate an opening, and
234
+ * `reached` is at least the page views that really got there. For a kind
235
+ * nearly everybody meets it is 1 and says nothing, which is the ordinary
236
+ * state rather than a fault.
237
+ */
238
+ readonly atMost: number | null;
239
+ /** The numerator of {@link atMost}: whole page views, which is what keeps it a bound. */
240
+ readonly atMostMet: number | null;
241
+ /**
242
+ * Appearances in excess of openings across the bearing placements — the
243
+ * straddle that divided out of each page's share before the pages met.
244
+ */
245
+ readonly drift: number;
246
+ /**
247
+ * Openings across the bearing placements whose reading no rollup has folded
248
+ * yet, which is exactly `openings − counted`.
249
+ *
250
+ * It does not bias the share; it says how much of the evidence behind it is
251
+ * still arriving, and how unequally — a lagging page weighs less than a
252
+ * caught-up one.
253
+ */
254
+ readonly pending: number;
255
+ /**
256
+ * Nobody's visit spanned a window and no opening is waiting, so the estimate
257
+ * and the ceiling are the same number and the share is exact.
258
+ *
259
+ * False under a silence.
260
+ */
261
+ readonly exact: boolean;
262
+ /**
263
+ * Placements reporting more reach than their page had appearances, which no
264
+ * rollup produces.
265
+ *
266
+ * Node counters older than the page-view column, or a caller that
267
+ * concatenated two reads. It is the one thing that can put {@link share}
268
+ * above 1, and a surface should show the census instead where it is
269
+ * non-nought.
270
+ */
271
+ readonly unreconciled: number;
272
+ readonly silence: KindReachSilence | null;
273
+ };
274
+ /**
275
+ * A page bearing a measured placement that the door could not scale, with the
276
+ * reason in the vocabulary a page's own reading publishes.
277
+ *
278
+ * **Not this reading's vocabulary**, and that is the point: the subject of a
279
+ * reason is a property of the reading it comes from, so a reason about a page
280
+ * is reported as a page's (0240). A funnel could reuse a reach silence outright
281
+ * because a funnel is asked of a page; a census of the library cannot, because
282
+ * its own subject is a kind — so the two vocabularies stand side by side here
283
+ * and the published table is what says they are one state at two subjects.
284
+ */
285
+ export type UnscaledPage = RevisionOf & {
286
+ readonly silence: ReachSilence;
287
+ };
288
+ /** What a deployment's library does for the readers who meet it, by kind of part. */
289
+ export type LibraryReach = {
290
+ /**
291
+ * Every type that stands anywhere, most readers missed first.
292
+ *
293
+ * Then the lower share, then by type, so two kinds that lose the same do not
294
+ * reorder on a refresh. A kind with no share sorts after one whose share is
295
+ * nought, because `null` is *nothing can be said* and not *nobody read it*.
296
+ */
297
+ readonly byType: readonly KindReach[];
298
+ /** Every role in the vocabulary, then the row for parts whose type declared none, in the same order. */
299
+ readonly byRole: readonly KindReach[];
300
+ /** Readings counted, which is revisions of pages and not trees. */
301
+ readonly pages: number;
302
+ /** Distinct trees across them. */
303
+ readonly trees: number;
304
+ /** Element nodes across them, which is the sum of every type row's placements. */
305
+ readonly placements: number;
306
+ /**
307
+ * Page views counted at the door across the pages read, added **once per
308
+ * page**.
309
+ *
310
+ * Addable for the reason no other count here is: a page view began on one
311
+ * revision of one tree and was counted once (0219). It is the weight behind
312
+ * the whole reading and is not the denominator of anything — a kind's own
313
+ * denominator counts a page once per place it stands there.
314
+ */
315
+ readonly arrivals: number;
316
+ /** Pages the door could scale, which is where every share here comes from. */
317
+ readonly scaled: number;
318
+ /**
319
+ * The pages bearing a measured placement that the door could not scale, by
320
+ * tree and newest revision first.
321
+ *
322
+ * The actionable half of every silence on a row above: one of these pages is
323
+ * why. Empty is the healthy state.
324
+ */
325
+ readonly unscaled: readonly UnscaledPage[];
326
+ /**
327
+ * The type that loses the most readers, which is the kind to look at first.
328
+ *
329
+ * By the **count** of page views missed and not by the share, for the reason
330
+ * a page's falls are ranked by the readers they lose (0221): a kind missed by
331
+ * two readers out of three is a worse rate and a smaller problem than one
332
+ * missed by four hundred out of a thousand. A type and never a role, because
333
+ * a type is the thing an author can replace.
334
+ */
335
+ readonly mostMissed: KindReach | null;
336
+ /**
337
+ * Readings of a revision beyond the first, which were dropped.
338
+ *
339
+ * A caller that concatenated two reads holds one page twice, and a page twice
340
+ * is the one way a weighted figure can lie about how much weight is behind
341
+ * it.
342
+ */
343
+ readonly duplicated: number;
344
+ /**
345
+ * Door rows for one revision beyond the first, which were ignored.
346
+ *
347
+ * A store keeps one row per revision, so this is a caller's two reads again —
348
+ * and adding them would double a page's arrivals and halve every share taken
349
+ * against it.
350
+ */
351
+ readonly duplicatedRows: number;
352
+ /**
353
+ * Types whose readings disagreed about the role they play, where the first
354
+ * reading's answer stands.
355
+ *
356
+ * Raised here rather than fetched from the census, because it is an alarm and
357
+ * because every role row below is about neither library when it is set. Both
358
+ * readings detect it off the same readings by the same rule, so they cannot
359
+ * disagree about it.
360
+ */
361
+ readonly roleDisagreed: readonly PrimitiveType[];
362
+ };
363
+ /**
364
+ * What a deployment's library does for the readers who meet it, by kind of
365
+ * part.
366
+ *
367
+ * Takes the readings and the whole window of page-view rows a deployment holds
368
+ * — each page's own row is picked out of them by the published matching rule
369
+ * (`pageViewsFor`) rather than by a third hand-written copy of it, because the
370
+ * pairing is the part of every join here that fails quietly when it is got
371
+ * wrong.
372
+ *
373
+ * Linear in the parts of the readings times the rows, with one pass that fills
374
+ * both groupings.
375
+ */
376
+ export declare const libraryReachOf: (readings: readonly PageReading[], rows: readonly StoredPageViews[]) => LibraryReach;
377
+ //# sourceMappingURL=library-reach.d.ts.map
@@ -0,0 +1,227 @@
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 { pageViewsFor, } from "./page-views.js";
7
+ export const KIND_REACH_SILENCES = everyMemberOf()(["unread", "unplaced", "unscaled", "unopened", "uncounted"]);
8
+ /** One line per silence, for a surface saying why a kind has no share of readers. */
9
+ export const describeKindReachSilence = (silence) => {
10
+ switch (silence) {
11
+ case "unread":
12
+ return "nothing reported a view of any place this kind of part stands";
13
+ case "unplaced":
14
+ return "nothing in the pages read is of this kind";
15
+ case "unscaled":
16
+ return "a page it stands on has no page views counted at the door, so its share is not comparable";
17
+ case "unopened":
18
+ return "a page it stands on has a row and nothing has said a page view began";
19
+ case "uncounted":
20
+ return "a page it stands on has readers and no window of their reading has been counted yet";
21
+ }
22
+ };
23
+ /** The kind-level reason a page's reason causes, which is the same state at the other subject. */
24
+ const KIND_REACH_OF_REACH = Object.freeze({
25
+ unmeasured: "unscaled",
26
+ unopened: "unopened",
27
+ uncounted: "uncounted",
28
+ });
29
+ const tallying = (kind) => ({
30
+ kind,
31
+ role: null,
32
+ placements: 0,
33
+ verdicts: 0,
34
+ unknown: 0,
35
+ pages: new Set(),
36
+ openings: 0,
37
+ counted: 0,
38
+ met: 0,
39
+ atMostMet: 0,
40
+ drift: 0,
41
+ pending: 0,
42
+ unreconciled: 0,
43
+ blocked: null,
44
+ });
45
+ /**
46
+ * One placement's contribution, which is nothing at all unless a window could
47
+ * speak for it.
48
+ *
49
+ * The door's reason is taken only from a page bearing a placement with a
50
+ * verdict: a kind that stands on a page nobody read is `unread` and not
51
+ * `unscaled`, because *nothing reported a view of it* is the better answer and
52
+ * the door has nothing to scale either way.
53
+ */
54
+ const add = (into, part, door, revision) => {
55
+ into.placements += 1;
56
+ if (part.standing === "unknown") {
57
+ into.unknown += 1;
58
+ return;
59
+ }
60
+ into.verdicts += 1;
61
+ into.pages.add(revision);
62
+ if (door.silence !== null) {
63
+ into.blocked ??= door.silence;
64
+ return;
65
+ }
66
+ const reached = part.counters?.reached ?? 0;
67
+ into.openings += door.opened;
68
+ into.counted += door.counted;
69
+ into.met += atDoorScale(reached, door);
70
+ into.atMostMet += Math.min(reached, door.opened);
71
+ into.drift += door.drift;
72
+ into.pending += door.pending;
73
+ into.unreconciled += reached > door.appearances ? 1 : 0;
74
+ };
75
+ /**
76
+ * The silence, with the reasons tried in the order they have to be tried in.
77
+ *
78
+ * Nothing of the kind before nothing measured, because *there is no such part
79
+ * in this library* is a better answer than *nobody was seen reading it* and the
80
+ * second is true of the first by accident. Nothing measured before the door,
81
+ * because a kind nobody read has no share whether or not it could be scaled.
82
+ */
83
+ const silenceOf = (of) => {
84
+ if (of.placements === 0)
85
+ return "unplaced";
86
+ if (of.verdicts === 0)
87
+ return "unread";
88
+ return of.blocked === null ? null : KIND_REACH_OF_REACH[of.blocked];
89
+ };
90
+ const rowOf = (of) => {
91
+ const silence = silenceOf(of);
92
+ const measured = silence === null;
93
+ return {
94
+ kind: of.kind,
95
+ role: of.kind.by === "type" ? of.role : null,
96
+ placements: of.placements,
97
+ verdicts: of.verdicts,
98
+ unknown: of.unknown,
99
+ pages: of.pages.size,
100
+ openings: measured ? of.openings : null,
101
+ counted: measured ? of.counted : null,
102
+ met: measured ? of.met : null,
103
+ missed: measured ? of.counted - of.met : null,
104
+ share: measured ? of.met / of.counted : null,
105
+ atMost: measured ? Math.min(1, of.atMostMet / of.openings) : null,
106
+ atMostMet: measured ? of.atMostMet : null,
107
+ drift: of.drift,
108
+ pending: of.pending,
109
+ exact: measured && of.drift === 0 && of.pending === 0 && of.unreconciled === 0,
110
+ unreconciled: of.unreconciled,
111
+ silence,
112
+ };
113
+ };
114
+ /** The name a row is ordered by, which is the key's own and never the row's position. */
115
+ const nameOf = (kind) => (kind.by === "type" ? kind.type : (kind.role ?? ""));
116
+ /**
117
+ * The worse of two, which is the ranking rule spelled once.
118
+ *
119
+ * Most readers missed, then the lower share, then by name — so a kind with no
120
+ * share at all sorts after one with a share of nought rather than above it.
121
+ */
122
+ const worseOf = (one, other) => (other.missed ?? -1) - (one.missed ?? -1) ||
123
+ (one.share ?? 2) - (other.share ?? 2) ||
124
+ nameOf(one.kind).localeCompare(nameOf(other.kind));
125
+ /** Tree id, then newest revision first, which is the order the page-view rows are read in. */
126
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) || other.revision - one.revision;
127
+ /**
128
+ * What a deployment's library does for the readers who meet it, by kind of
129
+ * part.
130
+ *
131
+ * Takes the readings and the whole window of page-view rows a deployment holds
132
+ * — each page's own row is picked out of them by the published matching rule
133
+ * (`pageViewsFor`) rather than by a third hand-written copy of it, because the
134
+ * pairing is the part of every join here that fails quietly when it is got
135
+ * wrong.
136
+ *
137
+ * Linear in the parts of the readings times the rows, with one pass that fills
138
+ * both groupings.
139
+ */
140
+ export const libraryReachOf = (readings, rows) => {
141
+ const tallies = new Map();
142
+ const seen = new Set();
143
+ const trees = new Set();
144
+ const unscaled = [];
145
+ const disagreed = new Set();
146
+ let pages = 0;
147
+ let placements = 0;
148
+ let arrivals = 0;
149
+ let scaled = 0;
150
+ let duplicated = 0;
151
+ let duplicatedRows = 0;
152
+ /**
153
+ * Every role in the vocabulary gets a row whether or not anything plays it,
154
+ * the way the census's role rows do: a role nothing in the library plays is a
155
+ * fact about the library worth having, and a surface that had to tell a
156
+ * missing row from an empty one would be reading the vocabulary itself.
157
+ */
158
+ for (const role of [...PRIMITIVE_ROLES, null]) {
159
+ const kind = { by: "role", role };
160
+ tallies.set(kindKeyOf(kind), tallying(kind));
161
+ }
162
+ for (const reading of readings) {
163
+ const revision = readingKeyOf(reading);
164
+ if (seen.has(revision)) {
165
+ duplicated += 1;
166
+ continue;
167
+ }
168
+ seen.add(revision);
169
+ trees.add(reading.treeId);
170
+ pages += 1;
171
+ const found = pageViewsFor(reading, rows);
172
+ const door = doorOf(found.measured);
173
+ duplicatedRows += found.duplicated;
174
+ arrivals += door.opened;
175
+ if (door.silence === null)
176
+ scaled += 1;
177
+ /**
178
+ * A page the door cannot scale is listed only where a window could speak
179
+ * for something on it: a page nobody read is not a page whose readers could
180
+ * not be counted, and listing it would put the commonest healthy state on
181
+ * the one list here that is meant to be empty.
182
+ */
183
+ if (door.silence !== null && reading.standings.unknown < reading.parts.length) {
184
+ unscaled.push({
185
+ treeId: reading.treeId,
186
+ revision: reading.revision,
187
+ silence: door.silence,
188
+ });
189
+ }
190
+ for (const part of reading.parts) {
191
+ const keys = [
192
+ { by: "type", type: part.type },
193
+ { by: "role", role: part.role },
194
+ ];
195
+ placements += 1;
196
+ for (const kind of keys) {
197
+ const key = kindKeyOf(kind);
198
+ const tally = tallies.get(key) ?? tallying(kind);
199
+ if (kind.by === "type") {
200
+ if (tally.placements === 0)
201
+ tally.role = part.role;
202
+ else if (tally.role !== part.role)
203
+ disagreed.add(part.type);
204
+ }
205
+ add(tally, part, door, revision);
206
+ tallies.set(key, tally);
207
+ }
208
+ }
209
+ }
210
+ const built = [...tallies.values()].map(rowOf);
211
+ const byType = built.filter((row) => row.kind.by === "type").sort(worseOf);
212
+ return {
213
+ byType,
214
+ byRole: built.filter((row) => row.kind.by === "role").sort(worseOf),
215
+ pages,
216
+ trees: trees.size,
217
+ placements,
218
+ arrivals,
219
+ scaled,
220
+ unscaled: [...unscaled].sort(byPage),
221
+ mostMissed: byType.find((row) => (row.missed ?? 0) > 0) ?? null,
222
+ duplicated,
223
+ duplicatedRows,
224
+ roleDisagreed: [...disagreed].sort((one, other) => one.localeCompare(other)),
225
+ };
226
+ };
227
+ //# sourceMappingURL=library-reach.js.map