@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,308 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { comparedAudiencesOf, crossesAudiences, } from "./audiences.js";
3
+ import { UNKNOWN_REGION } from "./region.js";
4
+ /**
5
+ * Whether two windows of a page were read by the same readership.
6
+ *
7
+ * Four readings in this subsystem compare two revisions — where the reading
8
+ * stops ([`change.ts`](change.ts)), the words a change put in front of readers
9
+ * ([`copy-change.ts`](copy-change.ts)), how much of a page gets read, and what
10
+ * readers did in it — and every one of them attributes the difference to the
11
+ * change. Each is careful about the arithmetic and none of them can see the one
12
+ * thing that would make the attribution wrong: **the readers were not the same
13
+ * people.** A page that was read by its home market in March and by a
14
+ * conference audience in April got better or worse for a reason no tree
15
+ * contains.
16
+ *
17
+ * Region is the only thing Loom knows about who a reader was, and it was built
18
+ * to be a map rather than an answer (0214). So this is the map asked a
19
+ * question: *the two windows were read by the same mix of places, so the
20
+ * comparison beside this one is comparing like with like* — or the other
21
+ * sentence, which is the valuable one.
22
+ *
23
+ * It is the eleventh thing taken out of what this subsystem already knows
24
+ * rather than collected: **nothing is added to a payload, a browser, a column,
25
+ * a store or the vocabulary of kinds**, and the broadcaster is not touched.
26
+ *
27
+ * ## It takes two readings, and that is the whole privacy design
28
+ *
29
+ * A region bucket is reported only once it is too large to be a person (0214),
30
+ * and a comparison is a second place that could give a small bucket away. *This
31
+ * country had forty readers and now has a figure we are withholding* says there
32
+ * are between one and twenty-four people in it, which is narrower than the
33
+ * floor promises and would be a leak out of the one subsystem that cannot
34
+ * afford one.
35
+ *
36
+ * So this takes two {@link RegionReading}s rather than two sets of rows, and
37
+ * the property that follows is structural rather than careful: **a figure
38
+ * appears here only where the floored reading it came from already published
39
+ * it.** The comparison cannot disclose more than the two maps it is built from,
40
+ * because it never sees more.
41
+ *
42
+ * The cost is one conflation and it is deliberate. A region named before and
43
+ * unnamed now has either emptied or fallen under the floor, and this cannot
44
+ * tell which — both are {@link RegionMovement} `thinned`. Separating them would
45
+ * be the leak again, said in two words instead of a number: nought names
46
+ * nobody, and one to twenty-four names somebody.
47
+ *
48
+ * The bucket that names nowhere is the one exception, and it is an exception
49
+ * for the same reason: it is never withheld, so its absence from a map is
50
+ * exactly nought rather than a withholding, and it is compared like a figure
51
+ * that was published. Without that, a platform that stopped placing its
52
+ * arrivals would read as the countries it drained having lost their readers.
53
+ *
54
+ * ## The counts are exact and are still not a trend
55
+ *
56
+ * Every other comparison here refuses counts, because two revisions are two
57
+ * windows of two trees read by two sets of readers and nothing divides out
58
+ * (0224). A region count is the one counter in this subsystem that is exact —
59
+ * stamped once, when a page view began, never recounted, and therefore addable
60
+ * across revisions and months (0214, 0219).
61
+ *
62
+ * It still is not a trend, for a different reason and a worse one. **A region
63
+ * counter has no window.** It is a running total per revision with nothing but
64
+ * an `updatedAt` on it, so a revision that has been live a month is compared
65
+ * against one that has been live a day, and the larger number is mostly the
66
+ * larger exposure. {@link ReadershipChange.arrivals} is therefore published as
67
+ * the weight behind the mix — *this moved among six hundred readers rather than
68
+ * six* — and no growth ratio is published at all, because the one anybody would
69
+ * quote would be a measurement of how long each revision had been up.
70
+ *
71
+ * The **mix** survives that, which is why it is the figure here: a composition
72
+ * is roughly the same over a day and over a month of the same audience, where a
73
+ * count is not.
74
+ *
75
+ * ## What `moved` is, and why there are two of it
76
+ *
77
+ * Half the sum of the absolute share movements, over the regions both maps
78
+ * name — the share of readers who would have to be somewhere else for the two
79
+ * windows to have the same mix. 0 is the same readership, 1 is two readerships
80
+ * with no country in common.
81
+ *
82
+ * It is a **floor**, because the regions one map names and the other withholds
83
+ * contribute a term nobody can evaluate, and every such term is at least
84
+ * nothing. {@link ReadershipChange.movedAtMost} adds the whole unaccounted
85
+ * share of both sides, which is the most those terms can come to. Where the
86
+ * floor withholds little the two numbers are nearly one number; where a page is
87
+ * quiet they open wide and {@link ReadershipComparability} `unsettled` is the
88
+ * honest answer rather than a verdict.
89
+ *
90
+ * ## Two questions about audiences, and only one of them is a refusal
91
+ *
92
+ * A map carries both an `audienceId` and a census of the audiences its rows
93
+ * named, and they are not two spellings of one fact (0297). The first is *which
94
+ * form this map is of*, which only a caller that picked one can say; the second
95
+ * is *what this map summed*, which every map can say.
96
+ *
97
+ * Only the first refuses. Two maps that each name a form, of two different
98
+ * forms, are two populations by construction and the comparison is withheld
99
+ * ({@link ReadershipComparability} `different-audiences`, 0294). Two maps read
100
+ * whole over a window holding two forms are a deployment's readers twice, which
101
+ * is the question this reading exists to answer, so the pair is compared and
102
+ * {@link ReadershipChange.populations} is what a surface says it over.
103
+ *
104
+ * The census cannot be made to refuse, and the reason is in the names: an
105
+ * `aud_` is a name the host chose for a predicate Loom never sees, so two
106
+ * different names are not two disjoint sets of people. `aud_everyone` is a name
107
+ * for everybody, and a window of it held against one of `aud_pro` is the
108
+ * migration 0294 refused to withhold rather than two readerships.
109
+ *
110
+ * Pure, linear in the buckets, and it reaches no store, clock or DOM.
111
+ */
112
+ /**
113
+ * How much of a readership has to move before a comparison of two windows is
114
+ * not comparing like with like.
115
+ *
116
+ * A tenth: one reader in ten would have to be somewhere else. It is a
117
+ * judgement, like every threshold in this subsystem, and it is **published and
118
+ * not overridable** for the reason the pace thresholds are (0218, 0230) — how
119
+ * much margin a claim needs is the framework's promise about its own
120
+ * confidence, where the words a page's readers get through in a minute is a
121
+ * fact about that page's text. A surface that wants a different line draws it
122
+ * on {@link ReadershipChange.moved}, which is published for exactly that.
123
+ */
124
+ export const READERSHIP_SHIFTED_ABOVE = 0.1;
125
+ export const REGION_MOVEMENTS = everyMemberOf()([
126
+ "grew",
127
+ "shrank",
128
+ "steady",
129
+ "thickened",
130
+ "thinned",
131
+ ]);
132
+ /** One line per movement, for a surface putting the comparison in front of a person. */
133
+ export const describeRegionMovement = (movement) => {
134
+ switch (movement) {
135
+ case "grew":
136
+ return "More page views began here than before.";
137
+ case "shrank":
138
+ return "Fewer page views began here than before.";
139
+ case "steady":
140
+ return "Exactly as many page views began here as before.";
141
+ case "thickened":
142
+ return "Too few page views began here to name before, and enough now.";
143
+ case "thinned":
144
+ return "Enough page views began here to name before, and too few now.";
145
+ }
146
+ };
147
+ export const READERSHIP_COMPARABILITIES = everyMemberOf()([
148
+ "like-for-like",
149
+ "shifted",
150
+ "unplaced",
151
+ "unsettled",
152
+ "unmeasured",
153
+ "incomparable",
154
+ "different-audiences",
155
+ ]);
156
+ /** One line per standing, for a surface putting the comparison in front of a person. */
157
+ export const describeReadershipComparability = (comparability) => {
158
+ switch (comparability) {
159
+ case "like-for-like":
160
+ return "The two windows were read by much the same mix of places.";
161
+ case "shifted":
162
+ return "The two windows were read by different mixes of places.";
163
+ case "unplaced":
164
+ return "What moved is the share of readers the platform could not place, which is a change in the measurement rather than in the readership.";
165
+ case "unsettled":
166
+ return "Too many buckets are below the floor to say whether the mix moved.";
167
+ case "unmeasured":
168
+ return "One of the two windows counted no page views.";
169
+ case "incomparable":
170
+ return "The two maps were read at different floors and were not compared.";
171
+ case "different-audiences":
172
+ return "The two maps are of different audiences, and so of different readers, and were not compared.";
173
+ }
174
+ };
175
+ const namedIn = (reading) => new Map(reading.regions.map((bucket) => [bucket.region, bucket.views]));
176
+ /**
177
+ * One window's figure for one region, where the map published one.
178
+ *
179
+ * **The unplaced bucket is the one region whose absence is exactly nought**,
180
+ * and the asymmetry is worth the special case. A floored map withholds a small
181
+ * placed bucket, so a placed region missing from it is either empty or nearly
182
+ * so and this cannot tell which. The unplaced bucket is never withheld
183
+ * (0214) — it names nowhere, so there is nobody in it to re-identify — which
184
+ * means a map without one was written by a platform that placed every arrival.
185
+ *
186
+ * Without it the commonest measurement fault this comparison exists to catch
187
+ * would be reported as its opposite: a proxy that stops writing the header
188
+ * fills a bucket that was not there before, so the unplaced share would carry
189
+ * no movement of its own and the whole shift would be attributed to the placed
190
+ * regions it drained.
191
+ */
192
+ const viewsIn = (named, region) => (region === UNKNOWN_REGION ? (named.get(region) ?? 0) : named.get(region));
193
+ const shareOf = (views, total) => views === undefined || total === 0 ? undefined : views / total;
194
+ const movementOf = (was, now) => {
195
+ if (was === undefined)
196
+ return "thickened";
197
+ if (now === undefined)
198
+ return "thinned";
199
+ if (now > was)
200
+ return "grew";
201
+ if (now < was)
202
+ return "shrank";
203
+ return "steady";
204
+ };
205
+ /** How many views a row moved, with a withheld side read as nought. */
206
+ const magnitudeOf = (row) => Math.abs((row.now.views ?? 0) - (row.was.views ?? 0));
207
+ /**
208
+ * Two windows' region maps, compared.
209
+ *
210
+ * The labels are the caller's: handing them the other way round reverses every
211
+ * sign rather than being refused, exactly as a before-and-after reading of a
212
+ * page does (0224). Both maps must be of the same tree, and a caller holding a
213
+ * window of rows over several revisions gets one with `regionReadingFor` in
214
+ * [`region.ts`](region.ts) rather than writing the filter.
215
+ */
216
+ export const readershipChangeOf = (was, now) => {
217
+ const audiences = comparedAudiencesOf(was, now);
218
+ const populations = { was: was.audiences, now: now.audiences };
219
+ /**
220
+ * Checked ahead of the floor, because it is not a floor fault and no floor
221
+ * fixes it: two maps of two populations read at one floor are still two
222
+ * populations, and this is the reading a surface leans on to decide whether a
223
+ * before-and-after is of like with like.
224
+ */
225
+ const crossAudience = crossesAudiences(was, now);
226
+ const incomparable = was.floor !== now.floor;
227
+ const unmeasured = was.views === 0 || now.views === 0;
228
+ const wasNamed = namedIn(was);
229
+ const nowNamed = namedIn(now);
230
+ const regions = [...new Set([...wasNamed.keys(), ...nowNamed.keys()])].map((region) => {
231
+ const wasViews = viewsIn(wasNamed, region);
232
+ const nowViews = viewsIn(nowNamed, region);
233
+ const wasSide = { views: wasViews, share: shareOf(wasViews, was.views) };
234
+ const nowSide = { views: nowViews, share: shareOf(nowViews, now.views) };
235
+ const both = wasSide.share !== undefined && nowSide.share !== undefined;
236
+ return {
237
+ region,
238
+ was: wasSide,
239
+ now: nowSide,
240
+ movement: movementOf(wasSide.views, nowSide.views),
241
+ shift: both ? (nowSide.share ?? 0) - (wasSide.share ?? 0) : undefined,
242
+ change: wasSide.views === undefined || nowSide.views === undefined
243
+ ? undefined
244
+ : nowSide.views - wasSide.views,
245
+ };
246
+ });
247
+ const arrivals = { was: was.views, now: now.views };
248
+ const withheld = crossAudience
249
+ ? "different-audiences"
250
+ : incomparable
251
+ ? "incomparable"
252
+ : unmeasured
253
+ ? "unmeasured"
254
+ : null;
255
+ if (withheld !== null) {
256
+ return {
257
+ floor: incomparable ? undefined : was.floor,
258
+ comparability: withheld,
259
+ audiences,
260
+ populations,
261
+ moved: undefined,
262
+ movedAtMost: undefined,
263
+ // Two differently floored maps publish nothing, because every row of the
264
+ // join would be an artefact of the two floors rather than a movement; two
265
+ // audiences' maps publish nothing because every row would be two
266
+ // populations' buckets held against each other. A window with no views
267
+ // keeps its rows: they are the other side's, and they are true of it.
268
+ regions: withheld === "unmeasured" ? ranked(regions) : [],
269
+ loudest: undefined,
270
+ // Nothing was compared, so neither window's views are accounted for.
271
+ unaccounted: { was: 1, now: 1 },
272
+ arrivals,
273
+ };
274
+ }
275
+ const shifted = regions.filter((row) => row.shift !== undefined);
276
+ const moved = shifted.reduce((total, row) => total + Math.abs(row.shift), 0) / 2;
277
+ // Clamped at nought, because a window whose every bucket is comparable sums
278
+ // its shares to 1 give or take a float's last bit, and a negative width would
279
+ // put the ceiling under the floor.
280
+ const accounted = (side) => Math.max(0, 1 - shifted.reduce((total, row) => total + (side(row) ?? 0), 0));
281
+ const unaccounted = {
282
+ was: accounted((row) => row.was.share),
283
+ now: accounted((row) => row.now.share),
284
+ };
285
+ const movedAtMost = Math.min(1, moved + (unaccounted.was + unaccounted.now) / 2);
286
+ const loudest = [...shifted].sort((one, other) => Math.abs(other.shift) - Math.abs(one.shift) || one.region.localeCompare(other.region))[0]?.region;
287
+ return {
288
+ floor: was.floor,
289
+ comparability: comparabilityOf(moved, movedAtMost, loudest),
290
+ audiences,
291
+ populations,
292
+ moved,
293
+ movedAtMost,
294
+ regions: ranked(regions),
295
+ loudest,
296
+ unaccounted,
297
+ arrivals,
298
+ };
299
+ };
300
+ /** Most views moved first, and by code where two moved the same, so a refresh does not reorder. */
301
+ const ranked = (regions) => [...regions].sort((one, other) => magnitudeOf(other) - magnitudeOf(one) || one.region.localeCompare(other.region));
302
+ const comparabilityOf = (moved, movedAtMost, loudest) => {
303
+ if (moved > READERSHIP_SHIFTED_ABOVE) {
304
+ return loudest === UNKNOWN_REGION ? "unplaced" : "shifted";
305
+ }
306
+ return movedAtMost > READERSHIP_SHIFTED_ABOVE ? "unsettled" : "like-for-like";
307
+ };
308
+ //# sourceMappingURL=readership.js.map
@@ -0,0 +1,173 @@
1
+ import type { TreeId } from "../ids.js";
2
+ import { type ReaderRegion, type RegionReading, type StoredRegionCount } from "./region.js";
3
+ /**
4
+ * Which of a deployment's pages the readers of one place opened.
5
+ *
6
+ * The region counter answers one question today and it is asked in one
7
+ * direction: *where were the readers of this page*, and *where were the
8
+ * readers of this deployment*. The rows hold more than that. A region row is a
9
+ * place, a page, a revision and a count of the page views that began — so the
10
+ * same rows, grouped the other way, answer *what do readers here read*, which
11
+ * is the question an operator asks second and could not ask at all.
12
+ *
13
+ * Nothing is collected for it. No payload field, no header, no column and no
14
+ * browser change: it is the eleventh thing taken out of the rows a deployment
15
+ * already has rather than added to what it takes, and the counter it reads is
16
+ * the exact one — a region view is counted once, at the moment a page view
17
+ * began, so it adds across revisions and across forms without drifting
18
+ * (0214).
19
+ *
20
+ * ## The floor applies to the cell, which is the whole of the design
21
+ *
22
+ * A region map withholds a bucket too small to be a readership. A breakdown of
23
+ * that bucket by page is **finer than the bucket**, and the floor has to follow
24
+ * it down: a country with four hundred views is a readership, and *one view of
25
+ * the careers page from Iceland* inside it is a person. Publishing the
26
+ * breakdown at the bucket's floor would hand back, one level down, exactly what
27
+ * the floor exists to refuse.
28
+ *
29
+ * So a page is named inside a region only where **its own count in that
30
+ * region** clears the floor, and what did not clear it is reported as a total
31
+ * naming no page — the same bargain the map strikes one level up, so the
32
+ * numbers still add to the views there were.
33
+ *
34
+ * Two consequences worth stating plainly, because both read as faults and
35
+ * neither is one:
36
+ *
37
+ * - **Most of a small deployment's breakdown is withheld.** A thousand views
38
+ * over ten pages and twenty countries has almost no cell above twenty-five.
39
+ * {@link RegionPageStanding} `unattributable` is that state named, and it is
40
+ * *this place's readers cannot be attributed to a page* rather than *nobody
41
+ * read anything*, which is the sentence a screen must never print over it.
42
+ * - **A region the map withheld has no breakdown at all.** The breakdowns are
43
+ * one per **named** bucket, in the map's own order, because naming a page
44
+ * inside an unnamed place would name the place.
45
+ *
46
+ * ## The unplaced bucket is broken down in full
47
+ *
48
+ * `unknown` is never withheld by the map, however small, because it names no
49
+ * place and there is nobody in it to re-identify. The same argument reaches its
50
+ * cells and so they are never withheld either: *two views of the pricing page
51
+ * from somewhere we cannot name* is strictly less than the door already
52
+ * publishes exactly, per revision, in `pageViews`.
53
+ *
54
+ * ## A cell is a place and a page, and never a revision or a form
55
+ *
56
+ * The cell sums every row of one page in one place — across the revisions the
57
+ * window holds and across the forms the page was served in.
58
+ *
59
+ * Across revisions because the question is about the page: a page read by
60
+ * thirty readers from one country over two revisions is a readership, and
61
+ * splitting it would withhold both halves and report a page nobody reads.
62
+ *
63
+ * Across forms because arrivals are people and a reader who arrived arrived
64
+ * once, whichever form they were served (0297). A page served in two forms has
65
+ * two rows for one country and is **one** page in one place, so it is named
66
+ * once — naming it twice would publish a deployment reading more pages than it
67
+ * serves, which is the direction this subsystem has been bitten in before.
68
+ *
69
+ * ## The map is held rather than restated
70
+ *
71
+ * {@link RegionPagesReading.map} is {@link regionReadingOf} over the same rows,
72
+ * unchanged. The totals a screen shows beside a breakdown are therefore the
73
+ * same numbers by construction rather than by agreement — two spellings of one
74
+ * rule that agree today is the fault this subsystem has been bitten by twice
75
+ * (0218, 0235), and a transpose that recounted its own buckets would be the
76
+ * third.
77
+ *
78
+ * ## The floor is asked for, not defaulted
79
+ *
80
+ * {@link RegionPagesOptions.floor} is required. The floor underneath is
81
+ * raise-only, so a reading called with nothing suppresses at the smallest
82
+ * bucket this runtime will ever name — and a deployment that raised its floor,
83
+ * read by a surface that forgot to say so, would publish cells about real
84
+ * people with nothing in the diff to show it (0322). A caller with nothing of
85
+ * its own to say passes `DEFAULT_REGION_FLOOR` and has said so.
86
+ *
87
+ * Pure and linear in the rows, with no store, clock or DOM, and no import that
88
+ * reaches a package.
89
+ */
90
+ /** What a screen may say about one region's breakdown by page. */
91
+ export type RegionPageStanding =
92
+ /** Every view in the bucket is on a page the breakdown names. */
93
+ "attributed"
94
+ /** Some of the bucket's views are on named pages and the rest are withheld. */
95
+ | "partly-attributed"
96
+ /**
97
+ * No page in this place cleared the floor, so the bucket's views are named
98
+ * and nothing in it is attributed.
99
+ *
100
+ * The claim worth acting on, and the one that must not be drawn as a place
101
+ * nobody read: the readers are in the map above, and it is the attribution
102
+ * that is withheld rather than the readership that is absent.
103
+ */
104
+ | "unattributable";
105
+ /** The closed set, for a surface accounting for every breakdown it draws. */
106
+ export declare const REGION_PAGE_STANDINGS: readonly RegionPageStanding[];
107
+ /** One line per standing, for a surface saying what a breakdown is withholding. */
108
+ export declare const describeRegionPageStanding: (standing: RegionPageStanding) => string;
109
+ /** One page the readers of a place opened. */
110
+ export type RegionPage = {
111
+ readonly treeId: TreeId;
112
+ /**
113
+ * Page views that began here, summed over the revisions and the forms the
114
+ * rows named.
115
+ */
116
+ readonly views: number;
117
+ /**
118
+ * This page's share of **the whole bucket**, including the views the
119
+ * breakdown withheld.
120
+ *
121
+ * The denominator is published rather than left to be derived because the two
122
+ * candidates differ and the obvious one is wrong: dividing by the named pages
123
+ * alone makes the shares sum to one and hides the withheld part, so a place
124
+ * whose attribution is mostly withheld would read as fully attributed.
125
+ *
126
+ * Absent only where the bucket's own total is nought, which is reachable on
127
+ * the unplaced bucket alone — it is named at any size, so rows of no views
128
+ * produce cells of no views and there is no quotient to take.
129
+ */
130
+ readonly share: number | undefined;
131
+ };
132
+ /** One named region, with the pages its readers opened. */
133
+ export type RegionPageBreakdown = {
134
+ readonly region: ReaderRegion;
135
+ /** The bucket's own total, which is the map's number unchanged. */
136
+ readonly views: number;
137
+ /** Pages with enough readers in this place to name, most-read first. */
138
+ readonly pages: readonly RegionPage[];
139
+ /** What was too small to name here, as a total that names no page. */
140
+ readonly withheld: {
141
+ readonly pages: number;
142
+ readonly views: number;
143
+ };
144
+ readonly standing: RegionPageStanding;
145
+ };
146
+ /** What a breakdown is read at. */
147
+ export type RegionPagesOptions = {
148
+ /**
149
+ * The floor under a named cell, which is the deployment's and is required.
150
+ *
151
+ * Raised above `DEFAULT_REGION_FLOOR` and never lowered below it. A caller
152
+ * with nothing of its own to say passes that constant.
153
+ */
154
+ readonly floor: number;
155
+ };
156
+ /** A region map and, for each place it named, what the readers there read. */
157
+ export type RegionPagesReading = {
158
+ /** The map itself, unchanged, so a breakdown's totals cannot disagree with it. */
159
+ readonly map: RegionReading;
160
+ /**
161
+ * One breakdown per named bucket, in the map's order, so a surface drawing
162
+ * both reads them side by side.
163
+ */
164
+ readonly regions: readonly RegionPageBreakdown[];
165
+ };
166
+ /**
167
+ * Rows from the store, read as a map and a breakdown of every place it named.
168
+ *
169
+ * Linear in the rows and in the places they name, with one pass to group the
170
+ * cells and one per named bucket to floor them.
171
+ */
172
+ export declare const regionPagesOf: (rows: readonly StoredRegionCount[], options: RegionPagesOptions) => RegionPagesReading;
173
+ //# sourceMappingURL=region-pages.d.ts.map
@@ -0,0 +1,62 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { UNKNOWN_REGION, regionReadingOf, } from "./region.js";
3
+ /** The closed set, for a surface accounting for every breakdown it draws. */
4
+ export const REGION_PAGE_STANDINGS = everyMemberOf()(["attributed", "partly-attributed", "unattributable"]);
5
+ /** One line per standing, for a surface saying what a breakdown is withholding. */
6
+ export const describeRegionPageStanding = (standing) => {
7
+ switch (standing) {
8
+ case "attributed":
9
+ return "every page view from this place is on a page named below";
10
+ case "partly-attributed":
11
+ return "some page views from this place are on named pages and the rest are withheld";
12
+ case "unattributable":
13
+ return "no page from this place has enough readers to name, so the readership is reported and the attribution is not";
14
+ }
15
+ };
16
+ /** Every row's page total within one place, keyed so two forms of a page are one page. */
17
+ const cellsIn = (rows) => {
18
+ const places = new Map();
19
+ for (const row of rows) {
20
+ const pages = places.get(row.region) ?? new Map();
21
+ pages.set(row.treeId, (pages.get(row.treeId) ?? 0) + row.views);
22
+ places.set(row.region, pages);
23
+ }
24
+ return places;
25
+ };
26
+ const breakdownOf = (bucket, cells, floor) => {
27
+ const counted = [...cells].map(([treeId, views]) => ({ treeId, views }));
28
+ const nameable = (cell) => bucket.region === UNKNOWN_REGION || cell.views >= floor;
29
+ const named = counted.filter(nameable);
30
+ const small = counted.filter((cell) => !nameable(cell));
31
+ const withheld = small.reduce((total, cell) => total + cell.views, 0);
32
+ return {
33
+ region: bucket.region,
34
+ views: bucket.views,
35
+ /** Most-read first, and by tree id where two are equal, so a refresh does not reorder. */
36
+ pages: named
37
+ .sort((one, other) => other.views - one.views || one.treeId.localeCompare(other.treeId))
38
+ .map(({ treeId, views }) => ({
39
+ treeId,
40
+ views,
41
+ share: bucket.views === 0 ? undefined : views / bucket.views,
42
+ })),
43
+ withheld: { pages: small.length, views: withheld },
44
+ standing: named.length === 0 ? "unattributable" : withheld === 0 ? "attributed" : "partly-attributed",
45
+ };
46
+ };
47
+ /**
48
+ * Rows from the store, read as a map and a breakdown of every place it named.
49
+ *
50
+ * Linear in the rows and in the places they name, with one pass to group the
51
+ * cells and one per named bucket to floor them.
52
+ */
53
+ export const regionPagesOf = (rows, options) => {
54
+ const map = regionReadingOf(rows, options);
55
+ const cells = cellsIn(rows);
56
+ const none = new Map();
57
+ return {
58
+ map,
59
+ regions: map.regions.map((bucket) => breakdownOf(bucket, cells.get(bucket.region) ?? none, map.floor)),
60
+ };
61
+ };
62
+ //# sourceMappingURL=region-pages.js.map