@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,381 @@
1
+ import { type ComparedAudiences, type ComparedPopulations } from "./audiences.js";
2
+ import type { ReaderRegion, RegionReading } from "./region.js";
3
+ /**
4
+ * Whether two windows of a page were read by the same readership.
5
+ *
6
+ * Four readings in this subsystem compare two revisions — where the reading
7
+ * stops ([`change.ts`](change.ts)), the words a change put in front of readers
8
+ * ([`copy-change.ts`](copy-change.ts)), how much of a page gets read, and what
9
+ * readers did in it — and every one of them attributes the difference to the
10
+ * change. Each is careful about the arithmetic and none of them can see the one
11
+ * thing that would make the attribution wrong: **the readers were not the same
12
+ * people.** A page that was read by its home market in March and by a
13
+ * conference audience in April got better or worse for a reason no tree
14
+ * contains.
15
+ *
16
+ * Region is the only thing Loom knows about who a reader was, and it was built
17
+ * to be a map rather than an answer (0214). So this is the map asked a
18
+ * question: *the two windows were read by the same mix of places, so the
19
+ * comparison beside this one is comparing like with like* — or the other
20
+ * sentence, which is the valuable one.
21
+ *
22
+ * It is the eleventh thing taken out of what this subsystem already knows
23
+ * rather than collected: **nothing is added to a payload, a browser, a column,
24
+ * a store or the vocabulary of kinds**, and the broadcaster is not touched.
25
+ *
26
+ * ## It takes two readings, and that is the whole privacy design
27
+ *
28
+ * A region bucket is reported only once it is too large to be a person (0214),
29
+ * and a comparison is a second place that could give a small bucket away. *This
30
+ * country had forty readers and now has a figure we are withholding* says there
31
+ * are between one and twenty-four people in it, which is narrower than the
32
+ * floor promises and would be a leak out of the one subsystem that cannot
33
+ * afford one.
34
+ *
35
+ * So this takes two {@link RegionReading}s rather than two sets of rows, and
36
+ * the property that follows is structural rather than careful: **a figure
37
+ * appears here only where the floored reading it came from already published
38
+ * it.** The comparison cannot disclose more than the two maps it is built from,
39
+ * because it never sees more.
40
+ *
41
+ * The cost is one conflation and it is deliberate. A region named before and
42
+ * unnamed now has either emptied or fallen under the floor, and this cannot
43
+ * tell which — both are {@link RegionMovement} `thinned`. Separating them would
44
+ * be the leak again, said in two words instead of a number: nought names
45
+ * nobody, and one to twenty-four names somebody.
46
+ *
47
+ * The bucket that names nowhere is the one exception, and it is an exception
48
+ * for the same reason: it is never withheld, so its absence from a map is
49
+ * exactly nought rather than a withholding, and it is compared like a figure
50
+ * that was published. Without that, a platform that stopped placing its
51
+ * arrivals would read as the countries it drained having lost their readers.
52
+ *
53
+ * ## The counts are exact and are still not a trend
54
+ *
55
+ * Every other comparison here refuses counts, because two revisions are two
56
+ * windows of two trees read by two sets of readers and nothing divides out
57
+ * (0224). A region count is the one counter in this subsystem that is exact —
58
+ * stamped once, when a page view began, never recounted, and therefore addable
59
+ * across revisions and months (0214, 0219).
60
+ *
61
+ * It still is not a trend, for a different reason and a worse one. **A region
62
+ * counter has no window.** It is a running total per revision with nothing but
63
+ * an `updatedAt` on it, so a revision that has been live a month is compared
64
+ * against one that has been live a day, and the larger number is mostly the
65
+ * larger exposure. {@link ReadershipChange.arrivals} is therefore published as
66
+ * the weight behind the mix — *this moved among six hundred readers rather than
67
+ * six* — and no growth ratio is published at all, because the one anybody would
68
+ * quote would be a measurement of how long each revision had been up.
69
+ *
70
+ * The **mix** survives that, which is why it is the figure here: a composition
71
+ * is roughly the same over a day and over a month of the same audience, where a
72
+ * count is not.
73
+ *
74
+ * ## What `moved` is, and why there are two of it
75
+ *
76
+ * Half the sum of the absolute share movements, over the regions both maps
77
+ * name — the share of readers who would have to be somewhere else for the two
78
+ * windows to have the same mix. 0 is the same readership, 1 is two readerships
79
+ * with no country in common.
80
+ *
81
+ * It is a **floor**, because the regions one map names and the other withholds
82
+ * contribute a term nobody can evaluate, and every such term is at least
83
+ * nothing. {@link ReadershipChange.movedAtMost} adds the whole unaccounted
84
+ * share of both sides, which is the most those terms can come to. Where the
85
+ * floor withholds little the two numbers are nearly one number; where a page is
86
+ * quiet they open wide and {@link ReadershipComparability} `unsettled` is the
87
+ * honest answer rather than a verdict.
88
+ *
89
+ * ## Two questions about audiences, and only one of them is a refusal
90
+ *
91
+ * A map carries both an `audienceId` and a census of the audiences its rows
92
+ * named, and they are not two spellings of one fact (0297). The first is *which
93
+ * form this map is of*, which only a caller that picked one can say; the second
94
+ * is *what this map summed*, which every map can say.
95
+ *
96
+ * Only the first refuses. Two maps that each name a form, of two different
97
+ * forms, are two populations by construction and the comparison is withheld
98
+ * ({@link ReadershipComparability} `different-audiences`, 0294). Two maps read
99
+ * whole over a window holding two forms are a deployment's readers twice, which
100
+ * is the question this reading exists to answer, so the pair is compared and
101
+ * {@link ReadershipChange.populations} is what a surface says it over.
102
+ *
103
+ * The census cannot be made to refuse, and the reason is in the names: an
104
+ * `aud_` is a name the host chose for a predicate Loom never sees, so two
105
+ * different names are not two disjoint sets of people. `aud_everyone` is a name
106
+ * for everybody, and a window of it held against one of `aud_pro` is the
107
+ * migration 0294 refused to withhold rather than two readerships.
108
+ *
109
+ * Pure, linear in the buckets, and it reaches no store, clock or DOM.
110
+ */
111
+ /**
112
+ * How much of a readership has to move before a comparison of two windows is
113
+ * not comparing like with like.
114
+ *
115
+ * A tenth: one reader in ten would have to be somewhere else. It is a
116
+ * judgement, like every threshold in this subsystem, and it is **published and
117
+ * not overridable** for the reason the pace thresholds are (0218, 0230) — how
118
+ * much margin a claim needs is the framework's promise about its own
119
+ * confidence, where the words a page's readers get through in a minute is a
120
+ * fact about that page's text. A surface that wants a different line draws it
121
+ * on {@link ReadershipChange.moved}, which is published for exactly that.
122
+ */
123
+ export declare const READERSHIP_SHIFTED_ABOVE = 0.1;
124
+ /**
125
+ * What happened to one region between the two windows.
126
+ *
127
+ * Three of the five compare two figures and two of them report that there is
128
+ * only one figure to have. No threshold decides between `grew`, `shrank` and
129
+ * `steady`: a region count is exact, so a difference of one view is a
130
+ * difference of one view, and the one-reader tests the other comparisons here
131
+ * need (0224) have nothing to do.
132
+ *
133
+ * The bucket that names nowhere is never `thickened` or `thinned`, because it
134
+ * is never withheld: a map without one placed every arrival it counted, so its
135
+ * absence is a nought that can be compared.
136
+ */
137
+ export type RegionMovement =
138
+ /** Named in both windows, and more views in the later one. */
139
+ "grew"
140
+ /** Named in both windows, and fewer views in the later one. */
141
+ | "shrank"
142
+ /** Named in both windows, and exactly as many views. */
143
+ | "steady"
144
+ /**
145
+ * Unnamed in the earlier window and named in the later one.
146
+ *
147
+ * Either it had nobody or it had too few to name, and which is not said.
148
+ */
149
+ | "thickened"
150
+ /**
151
+ * Named in the earlier window and unnamed in the later one.
152
+ *
153
+ * The same conflation the other way round, and the one worth being clear
154
+ * about: this is **not** *the readers from this country stopped coming*. It
155
+ * is *there are no longer enough of them to say*, which includes none of
156
+ * them and includes nearly enough of them.
157
+ */
158
+ | "thinned";
159
+ export declare const REGION_MOVEMENTS: readonly RegionMovement[];
160
+ /** One line per movement, for a surface putting the comparison in front of a person. */
161
+ export declare const describeRegionMovement: (movement: RegionMovement) => string;
162
+ /** What one window's map said about one region, where it said anything. */
163
+ export type RegionSide = {
164
+ /** Page views that began here, or `undefined` where the floor withheld the bucket. */
165
+ readonly views: number | undefined;
166
+ /**
167
+ * {@link views} over every view in that window, named and withheld, or
168
+ * `undefined` with it.
169
+ *
170
+ * The denominator is the window's whole total rather than its named buckets,
171
+ * so the shares of a map sum to below 1 by exactly what the floor is holding
172
+ * back. Normalising over the named buckets would make a quiet window's shares
173
+ * add to 1 and read as a complete picture of nothing.
174
+ */
175
+ readonly share: number | undefined;
176
+ };
177
+ /** One region, as the two windows' maps have it. */
178
+ export type ComparedRegion = {
179
+ readonly region: ReaderRegion;
180
+ readonly was: RegionSide;
181
+ readonly now: RegionSide;
182
+ readonly movement: RegionMovement;
183
+ /**
184
+ * `now.share − was.share`, or `undefined` where either window withheld the
185
+ * bucket.
186
+ *
187
+ * Signed, and the terms this is summed into are what
188
+ * {@link ReadershipChange.moved} is. A row with no shift is a row that is
189
+ * counted in the unaccounted share instead, which is the same fact said as a
190
+ * bound rather than as a figure.
191
+ */
192
+ readonly shift: number | undefined;
193
+ /**
194
+ * `now.views − was.views`, or `undefined` where either window withheld the
195
+ * bucket.
196
+ *
197
+ * Exact where it is published, and still not a trend: the two windows are two
198
+ * revisions' running totals and were not up for the same length of time.
199
+ */
200
+ readonly change: number | undefined;
201
+ };
202
+ /**
203
+ * Whether the comparison beside this one is comparing like with like.
204
+ *
205
+ * Six members, and four of them are answers. There is no silence vocabulary
206
+ * here for the reason a reading of what readers did needs none (0242): every
207
+ * state in which a figure is missing is one of these, so a withheld `moved` and
208
+ * a standing can never disagree about why.
209
+ */
210
+ export type ReadershipComparability =
211
+ /**
212
+ * The mix cannot have moved far enough to matter — `movedAtMost` is under the
213
+ * line, so the withheld buckets cannot carry it over.
214
+ */
215
+ "like-for-like"
216
+ /** The mix moved, and the region that moved most is a place. */
217
+ | "shifted"
218
+ /**
219
+ * The mix moved, and the region that moved most is the bucket that names
220
+ * nowhere.
221
+ *
222
+ * Worth its own member because it is almost never a fact about readers. The
223
+ * unplaced bucket is what the platform in front of the application did not
224
+ * say (0214), so a swing in it is a proxy changed, a header dropped or a CDN
225
+ * rerouted — a change in the measurement rather than in the readership, and a
226
+ * surface that called it an audience shift would send somebody looking for
227
+ * the wrong thing.
228
+ */
229
+ | "unplaced"
230
+ /**
231
+ * `moved` is under the line and `movedAtMost` is over it: the floor is
232
+ * withholding enough that the question cannot be answered either way.
233
+ *
234
+ * The ordinary state of a quiet page, and a correct answer rather than a
235
+ * fault. A deployment that wants it settled needs more readers, not a smaller
236
+ * floor.
237
+ */
238
+ | "unsettled"
239
+ /** One of the two windows counted no page views at all, so there is no mix to compare. */
240
+ | "unmeasured"
241
+ /**
242
+ * The two maps were floored differently, so nothing was compared.
243
+ *
244
+ * A bucket named in one and withheld in the other would then be an artefact
245
+ * of the two floors rather than a movement of readers, and every figure built
246
+ * on it would inherit that. Read both sides at the same floor — the higher of
247
+ * the two, since a floor is raise-only.
248
+ */
249
+ | "incomparable"
250
+ /**
251
+ * The two maps are of two audiences, so nothing was compared.
252
+ *
253
+ * This reading exists to say whether the comparison beside it is of like with
254
+ * like, and a pair of two populations is the one case where the answer is
255
+ * known in advance and is *no*. Two forms of a page (0263) are served to two
256
+ * sets of readers by construction, so every shift here would be the
257
+ * difference between two audiences' geographies reported as a readership that
258
+ * moved — and reported by the one reading a surface trusts to catch exactly
259
+ * that.
260
+ *
261
+ * Refused only where both maps name an audience and the two differ; a pair
262
+ * spanning the migration that added the column (0284), or one built by
263
+ * `regionReadingOf` over a whole window, names none and is compared with the
264
+ * two names in {@link ReadershipChange.audiences}.
265
+ */
266
+ | "different-audiences";
267
+ export declare const READERSHIP_COMPARABILITIES: readonly ReadershipComparability[];
268
+ /** One line per standing, for a surface putting the comparison in front of a person. */
269
+ export declare const describeReadershipComparability: (comparability: ReadershipComparability) => string;
270
+ /** What the comparison could not account for, as a share of each window's views. */
271
+ export type UnaccountedShares = {
272
+ readonly was: number;
273
+ readonly now: number;
274
+ };
275
+ /** How many page views began in each window, which is the weight and never a trend. */
276
+ export type Arrivals = {
277
+ readonly was: number;
278
+ readonly now: number;
279
+ };
280
+ /** Two windows' readerships, held against each other. */
281
+ export type ReadershipChange = {
282
+ /**
283
+ * The floor both maps were read at, or `undefined` where they differ and
284
+ * nothing was compared.
285
+ */
286
+ readonly floor: number | undefined;
287
+ readonly comparability: ReadershipComparability;
288
+ /**
289
+ * The audience each map was of, where it named one.
290
+ *
291
+ * As every comparison in this subsystem carries it, and for the same reason: a
292
+ * `null` on either side is why a pair of two populations can be compared here
293
+ * rather than refused, and a surface saying so needs the field to say it.
294
+ */
295
+ readonly audiences: ComparedAudiences;
296
+ /**
297
+ * The audiences each map's rows named, which is what each side was a sum
298
+ * over.
299
+ *
300
+ * Beside {@link ReadershipChange.audiences} rather than instead of it,
301
+ * because the two answer different questions and a surface needs both: that
302
+ * one is the form each map is **of**, this one is the forms each map **added
303
+ * up**. A map read whole over a deployment serving two audiences names no
304
+ * form and has two members here, which is the ordinary case for a deployment
305
+ * serving two forms of a page (0263) and the one this field exists for.
306
+ * *Both of these maps are sums over two of the forms you serve* is a caption,
307
+ * where the silence that was there before was indistinguishable from a window
308
+ * that named nothing at all.
309
+ *
310
+ * **Nothing is refused on it** (0297). A deployment's two forms are served to
311
+ * two sets of readers, but the readers are people and a person who arrived
312
+ * arrived once — so adding two forms' arrivals is one readership, unlike
313
+ * adding two forms' node counters, which is one number about two pages
314
+ * (0290). Carried under a silence and under none, as every census here is.
315
+ */
316
+ readonly populations: ComparedPopulations;
317
+ /**
318
+ * Half the sum of the absolute share movements over the regions both maps
319
+ * name, in `[0, 1]`, or `undefined` where nothing was compared.
320
+ *
321
+ * A floor on how much the readership moved. The share of readers who would
322
+ * have to be somewhere else for the two windows to have the same mix.
323
+ */
324
+ readonly moved: number | undefined;
325
+ /**
326
+ * {@link moved} plus the whole unaccounted share of both windows, capped at
327
+ * 1, or `undefined` with it.
328
+ *
329
+ * A ceiling, and the two numbers together are the only honest statement this
330
+ * can make on a page whose buckets are mostly under the floor.
331
+ */
332
+ readonly movedAtMost: number | undefined;
333
+ /**
334
+ * Every region either map names, most-moved first.
335
+ *
336
+ * Ranked by views moved rather than by share moved, which is the ranking rule
337
+ * this subsystem uses everywhere (0221): a country of forty readers that
338
+ * halved is a smaller fact than one of four hundred that moved a tenth. A
339
+ * `thinned` or `thickened` row is ranked by the one figure it has, which
340
+ * treats the withheld side as nought and therefore ranks such a row as high
341
+ * as it could possibly deserve.
342
+ */
343
+ readonly regions: readonly ComparedRegion[];
344
+ /**
345
+ * The region carrying the largest absolute {@link ComparedRegion.shift}, or
346
+ * `undefined` where no region is named in both maps.
347
+ *
348
+ * What `shifted` and `unplaced` are told apart by, and the first thing a
349
+ * person reading a shifted comparison wants.
350
+ */
351
+ readonly loudest: ReaderRegion | undefined;
352
+ /**
353
+ * The share of each window's views that is in no comparable row: its withheld
354
+ * buckets, and the buckets the other window withheld.
355
+ *
356
+ * The width of the bound on {@link moved}, and a measurement in its own
357
+ * right — a deployment reading two thirds of its arrivals as unaccounted is
358
+ * being told that its traffic is spread thinner than its floor, which no
359
+ * single window's map says.
360
+ */
361
+ readonly unaccounted: UnaccountedShares;
362
+ /**
363
+ * Page views that began in each window, named and withheld.
364
+ *
365
+ * Exact (0214, 0219), and deliberately not divided one by the other: the two
366
+ * revisions were not up for the same length of time, and nothing in these
367
+ * rows says how long either was.
368
+ */
369
+ readonly arrivals: Arrivals;
370
+ };
371
+ /**
372
+ * Two windows' region maps, compared.
373
+ *
374
+ * The labels are the caller's: handing them the other way round reverses every
375
+ * sign rather than being refused, exactly as a before-and-after reading of a
376
+ * page does (0224). Both maps must be of the same tree, and a caller holding a
377
+ * window of rows over several revisions gets one with `regionReadingFor` in
378
+ * [`region.ts`](region.ts) rather than writing the filter.
379
+ */
380
+ export declare const readershipChangeOf: (was: RegionReading, now: RegionReading) => ReadershipChange;
381
+ //# sourceMappingURL=readership.d.ts.map