@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,268 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { formKeyOf, readingKeyOf } from "./audiences.js";
3
+ import { pageViewsFor } from "./page-views.js";
4
+ export const DEPLOYMENT_CHANGE_SILENCES = everyMemberOf()([
5
+ "unread",
6
+ "mispaired",
7
+ "unsplit",
8
+ "unscaled",
9
+ "unopened",
10
+ "inconsistent",
11
+ ]);
12
+ export const MOVEMENT_STANDINGS = everyMemberOf()([
13
+ "ranked",
14
+ "unmoved",
15
+ "unread",
16
+ "mispaired",
17
+ "unsplit",
18
+ "unscaled",
19
+ "unopened",
20
+ "inconsistent",
21
+ ]);
22
+ /** One line per standing, for a surface naming why a page is where it is. */
23
+ export const describeMovementStanding = (standing) => {
24
+ switch (standing) {
25
+ case "ranked":
26
+ return "in an order, by the readers its sharpest movement moves at the door's scale";
27
+ case "unmoved":
28
+ return "compared, and nothing on it moved by as much as one reader";
29
+ case "unread":
30
+ return "one of the two windows reported no view of its revision";
31
+ case "mispaired":
32
+ return "the two readings are of different pages, so there is no movement here";
33
+ case "unsplit":
34
+ return "one window holds two forms of the page and says which readers neither";
35
+ case "unscaled":
36
+ return "no page views counted at the later door, so its movement is not comparable with another page's";
37
+ case "unopened":
38
+ return "the later page-view row is there and nothing has said a page view began";
39
+ case "inconsistent":
40
+ return "it reports more readers at a stop than have ever appeared";
41
+ }
42
+ };
43
+ const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(MOVEMENT_STANDINGS.map((standing) => [standing, 0])));
44
+ /**
45
+ * The form this comparison is of, under the published rule.
46
+ *
47
+ * `formKeyOf` was written in this module and now lives beside `readingKeyOf`,
48
+ * for the reason that one is published: four library comparisons had the defect
49
+ * it fixes and no key to import, so each spelled the pairing by tree alone
50
+ * (0293). The difference between the two rules is written where they are
51
+ * published.
52
+ *
53
+ * The audience is the later window's, for the reason only the later window's
54
+ * rows are asked for.
55
+ */
56
+ const formKeyOfChange = (change) => formKeyOf({ treeId: change.treeId, audienceId: change.progress.now.audienceId });
57
+ /**
58
+ * What makes two reads of a comparison the same read: the form, and the two
59
+ * revisions it compared.
60
+ *
61
+ * The form carries the audience, for the reason `readingKeyOf` does (0290): a
62
+ * page is one base tree and the deltas an audience earns, so two forms of it
63
+ * are compared over the same two revisions, and a key without the audience
64
+ * makes the second form's comparison the first one handed in twice.
65
+ */
66
+ const pairKeyOf = (change) => `${formKeyOfChange(change)}\u0000${change.revisions.was}\u0000${change.revisions.now}`;
67
+ /**
68
+ * One direction's movement, scaled where the page has a scale.
69
+ *
70
+ * The magnitude is taken of the comparison's own ranking figure rather than
71
+ * multiplied up again here, because deriving it twice is how two screens come to
72
+ * disagree about which band a change hurt.
73
+ */
74
+ const movementOf = (at, inflation) => at === null
75
+ ? null
76
+ : {
77
+ at,
78
+ share: Math.abs(at.improvement),
79
+ readers: inflation === null ? null : Math.abs(at.readersKept) / (1 + inflation),
80
+ };
81
+ /**
82
+ * The standing a comparison's own silence puts a page in.
83
+ *
84
+ * Two of the four comparison silences name themselves here and two share
85
+ * `unread`, which is the coarser bucket and is deliberate: `different-audiences`
86
+ * and `nothing-measured` are both *there was nothing to compare on one side*,
87
+ * and the cause travels on {@link MovedPage.silence} for a surface that wants
88
+ * to say which. `audiences-mixed` does not share it, because what it has in
89
+ * common with them is a nought rather than a state of a deployment's readers
90
+ * (0301).
91
+ *
92
+ * **That the cause travels is now asserted rather than promised**, by a pair
93
+ * of fixtures standing the two side by side, so the day a fourth standing is
94
+ * taken — proposed, in a record of its own awaiting review — there is a test
95
+ * that says what moved.
96
+ */
97
+ const standingFor = (silence) => {
98
+ switch (silence) {
99
+ case "different-trees":
100
+ return "mispaired";
101
+ case "audiences-mixed":
102
+ return "unsplit";
103
+ case "different-audiences":
104
+ case "nothing-measured":
105
+ return "unread";
106
+ }
107
+ };
108
+ /**
109
+ * One page's row, with the reasons tried in the order they have to be tried in.
110
+ *
111
+ * The comparison's own silence first, because *there was nothing to compare* is
112
+ * a better answer than *its movement could not be scaled*. The door next,
113
+ * because a page with no scale has nothing to put a movement on. Then the gate
114
+ * the comparison itself applies, so a page nothing moved is not reported as a
115
+ * page whose counters disagree with its row. And the disagreement last, because
116
+ * it is a statement about a stop and a row together.
117
+ */
118
+ const rowOf = (change, door) => {
119
+ const where = {
120
+ treeId: change.treeId,
121
+ revisions: change.revisions,
122
+ audienceId: change.progress.now.audienceId,
123
+ views: { was: change.progress.was.views, now: change.progress.now.views },
124
+ opened: door?.opened ?? null,
125
+ inflation: door?.inflation ?? null,
126
+ silence: change.silence,
127
+ };
128
+ const nothing = { worsened: null, improved: null };
129
+ if (change.silence !== null) {
130
+ return { ...where, ...nothing, standing: standingFor(change.silence) };
131
+ }
132
+ if (door === null)
133
+ return { ...where, ...nothing, standing: "unscaled" };
134
+ /**
135
+ * A null inflation is exactly an opened of nought — the page-view reading
136
+ * withholds the fraction rather than dividing by nothing — so the check is
137
+ * written on the figure the scale needs and not on the count behind it.
138
+ */
139
+ if (door.inflation === null)
140
+ return { ...where, ...nothing, standing: "unopened" };
141
+ if (change.mostLost === null && change.mostKept === null) {
142
+ return { ...where, ...nothing, standing: "unmoved" };
143
+ }
144
+ const beyond = (at) => at !== null && at.now.reached > door.appearances;
145
+ if (beyond(change.mostLost) || beyond(change.mostKept)) {
146
+ return {
147
+ ...where,
148
+ standing: "inconsistent",
149
+ worsened: movementOf(change.mostLost, null),
150
+ improved: movementOf(change.mostKept, null),
151
+ };
152
+ }
153
+ return {
154
+ ...where,
155
+ standing: "ranked",
156
+ worsened: movementOf(change.mostLost, door.inflation),
157
+ improved: movementOf(change.mostKept, door.inflation),
158
+ };
159
+ };
160
+ /** Tree id, then newest later revision first, which is the order a page's rows are read in. */
161
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) ||
162
+ other.revisions.now - one.revisions.now ||
163
+ (one.audienceId ?? "").localeCompare(other.audienceId ?? "");
164
+ /**
165
+ * The sharper of two movements in one direction, which is the ranking rule
166
+ * spelled once.
167
+ *
168
+ * By readers before share, for the reason a page ranks its own stops that way
169
+ * (0221, 0224): a stop two readers out of three left is a worse rate and a
170
+ * smaller problem than one four hundred out of a thousand left.
171
+ */
172
+ const sharperOn = (direction) => (one, other) => (other[direction]?.readers ?? 0) - (one[direction]?.readers ?? 0) ||
173
+ (other[direction]?.share ?? 0) - (one[direction]?.share ?? 0) ||
174
+ byPage(one, other);
175
+ /**
176
+ * What a change did across a deployment's pages, as two orders.
177
+ *
178
+ * Takes the comparisons rather than the counters, for the reason every derived
179
+ * reading in this subsystem does: the movements and the gates are what this is
180
+ * made of, and deriving them twice is how two screens come to disagree. A caller
181
+ * with two windows of counters reads each page's parts, then its progress, then
182
+ * its comparison, then this.
183
+ *
184
+ * The rows are the **later** window's page-view rows — the whole window a
185
+ * deployment holds, not one page's — because the figure being scaled is the
186
+ * later window's own. Each page's row is picked out by the published rule, so no
187
+ * caller writes the matching itself.
188
+ */
189
+ export const deploymentChangeOf = (changes, rows) => {
190
+ /**
191
+ * Grouped by **form** rather than by page. Two forms of one page are two live
192
+ * things with two movements of their own (0290), so a tree handed in with one
193
+ * comparison per form is not the ambiguity this gate exists for — it is a
194
+ * deployment serving two audiences. What is still ambiguous is one *form*
195
+ * handed in with two different revision pairs, which is the state the
196
+ * one-window order deliberately keeps as two rows and which a comparison
197
+ * cannot reduce to one.
198
+ */
199
+ const pairsByForm = new Map();
200
+ for (const change of changes) {
201
+ const pairs = pairsByForm.get(formKeyOfChange(change)) ?? new Set();
202
+ pairs.add(pairKeyOf(change));
203
+ pairsByForm.set(formKeyOfChange(change), pairs);
204
+ }
205
+ const unsettled = (change) => (pairsByForm.get(formKeyOfChange(change))?.size ?? 0) > 1;
206
+ /**
207
+ * Named by tree, because a page is what a surface draws and the tree id is
208
+ * what it has. A deployment whose two forms are *each* ambiguous names the
209
+ * tree once, and a tree one of whose forms is sound still names it — that
210
+ * form is read, and the name says a reading of this page is incomplete.
211
+ */
212
+ const ambiguous = [...new Set(changes.filter(unsettled).map((change) => change.treeId))].sort((one, other) => one.localeCompare(other));
213
+ const unreadable = new Set(changes.filter(unsettled).map(formKeyOfChange));
214
+ const seen = new Set();
215
+ const counted = new Set();
216
+ const read = [];
217
+ let duplicated = 0;
218
+ let duplicatedRows = 0;
219
+ let arrivals = 0;
220
+ for (const change of changes) {
221
+ if (unreadable.has(formKeyOfChange(change)))
222
+ continue;
223
+ const key = pairKeyOf(change);
224
+ if (seen.has(key)) {
225
+ duplicated += 1;
226
+ continue;
227
+ }
228
+ seen.add(key);
229
+ /**
230
+ * The audience travels with the asking, so the door row picked is this
231
+ * form's own (0290). Dropping it here would divide one form's movement by
232
+ * a row that may be the other form's, chosen by the caller's array order.
233
+ */
234
+ const later = {
235
+ treeId: change.progress.now.treeId,
236
+ revision: change.revisions.now,
237
+ audienceId: change.progress.now.audienceId,
238
+ };
239
+ const door = pageViewsFor(later, rows);
240
+ const doorKey = readingKeyOf(later);
241
+ duplicatedRows += door.duplicated;
242
+ if (!counted.has(doorKey)) {
243
+ counted.add(doorKey);
244
+ arrivals += door.measured?.opened ?? 0;
245
+ }
246
+ read.push(rowOf(change, door.measured));
247
+ }
248
+ const harmed = read.filter((row) => row.worsened?.readers != null).sort(sharperOn("worsened"));
249
+ const helped = read.filter((row) => row.improved?.readers != null).sort(sharperOn("improved"));
250
+ const ranked = new Set([...harmed, ...helped]);
251
+ const standings = { ...EMPTY_STANDINGS };
252
+ for (const row of read)
253
+ standings[row.standing] += 1;
254
+ return {
255
+ harmed,
256
+ helped,
257
+ unranked: read.filter((row) => !ranked.has(row)).sort(byPage),
258
+ worst: harmed[0] ?? null,
259
+ best: helped[0] ?? null,
260
+ standings,
261
+ compared: read.length,
262
+ arrivals,
263
+ duplicated,
264
+ duplicatedRows,
265
+ ambiguous,
266
+ };
267
+ };
268
+ //# sourceMappingURL=deployment-change.js.map
@@ -0,0 +1,265 @@
1
+ import type { AudienceId } from "../audience/audience.js";
2
+ import type { TreeId } from "../ids.js";
3
+ import { type StoredPageViews } from "./page-views.js";
4
+ import type { ReadingProgress, ReadingStop } from "./progress.js";
5
+ /**
6
+ * Which of a deployment's pages to fix first.
7
+ *
8
+ * Every reading in this subsystem answers about one revision of one page: where
9
+ * its reading stops, how much of what it says gets read, whether a change made
10
+ * room to read it. A deployment has forty of them, and nothing until now could
11
+ * put them in an order — so the first question anybody opening a portal asks,
12
+ * *where is the problem*, was the one question the counters could not be asked.
13
+ *
14
+ * This is that order, taken off the readings a deployment already has and
15
+ * nothing else: no payload, no browser change, no counter that does not exist,
16
+ * no column and no byte on any wire.
17
+ *
18
+ * ## A count is comparable across two pages only once the door has scaled it
19
+ *
20
+ * Inside one page a fall is reported as a ratio of two counts off the same rows,
21
+ * and the over-count in a distinct view count very nearly divides out: a reader
22
+ * who straddled a rollup window straddled it for the whole page
23
+ * ([0221](../../decisions/0221-where-reading-stops-is-a-fall-between-two-siblings-and-a-ratio-of-two-counts-off-one-row-set.md)).
24
+ *
25
+ * **Across two pages it does not divide out, because the straddle rate is each
26
+ * page's own.** A page readers linger on for twenty minutes, against a rollup
27
+ * window of five, posts its batches into four windows and has every distinct
28
+ * count against it inflated roughly fourfold; a page read in ninety seconds
29
+ * does not. Ranking the raw losses therefore ranks partly by how long readers
30
+ * stay, which is not the question anybody asked.
31
+ *
32
+ * So the ranking key is the loss put **on the scale the door counts in**:
33
+ * `lost ÷ (1 + inflation)`, where the inflation is that page's own
34
+ * `drift ÷ opened` off that page's own door row. The rule for picking the right
35
+ * row is published beside the counter it is a rule about and is reused here
36
+ * rather than written a second time
37
+ * ([0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)).
38
+ *
39
+ * The figure that comes out is not a count of people and is deliberately not
40
+ * rounded into one. It is a loss stated at the door's scale, which is what makes
41
+ * two pages' losses the same kind of number.
42
+ *
43
+ * ## A page the door cannot scale is not ranked against one it can
44
+ *
45
+ * A page can be perfectly well measured and still have no place in the order:
46
+ * its counters are full of readers and its door row is missing, expired, or
47
+ * predates the column. Mixing its unscaled loss in with scaled ones would put it
48
+ * in the order at the wrong height, and there is no direction that is the safe
49
+ * one — a long-dwell page would be over-ranked and a quick one under-ranked.
50
+ *
51
+ * So it is reported out of the order rather than in it, with the standing saying
52
+ * which of four reasons applies. That is the same refusal a region map makes
53
+ * about a bucket it may not publish: the figure a surface could misread is one
54
+ * the function never offers.
55
+ *
56
+ * ## What is deliberately not published
57
+ *
58
+ * **No deployment-wide loss.** The artefact is an order and not a sum. Two
59
+ * revisions of one tree are two live versions of one page and both belong in the
60
+ * order, so anything that added their losses would count one page's problem
61
+ * twice — and a count that has been added cannot be unadded
62
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
63
+ * A ranking cannot double-count, because nothing in it is added: the only error
64
+ * available to it is one page standing in it twice, and that is the one thing
65
+ * deduplicated here.
66
+ *
67
+ * The one figure that is added is `arrivals`, and it is addable for the reason
68
+ * every other counter here is not: a page view began on exactly one revision of
69
+ * exactly one tree, was counted once at the door, and is never recounted.
70
+ *
71
+ * Pure, linear in the pages times the rows, and reaches no store, clock or DOM.
72
+ */
73
+ /** A reason a page has no place in the order. */
74
+ export type DeploymentSilence =
75
+ /**
76
+ * The window's counters report no view of this revision.
77
+ *
78
+ * There is no fall to rank because there was no reading, and this is checked
79
+ * before the door is, so a page nobody opened is not reported as a page the
80
+ * door could not scale.
81
+ *
82
+ * **It means what it says, which it did not before.** A reading refused for
83
+ * holding two forms of the page publishes the same nought
84
+ * ({@link ReadingProgress.views}), so until `unsplit` existed this standing
85
+ * was printed over a window full of readers (0301).
86
+ */
87
+ "unread"
88
+ /**
89
+ * The reading handed in holds two forms of the page and named neither, so it
90
+ * was read as neither population.
91
+ *
92
+ * **Not a page nobody read, which is what it was reported as.** A page served
93
+ * in two forms (0263) has two sets of counters over one tree at one revision,
94
+ * and a page reading handed both with no audience asked for reads neither:
95
+ * every part is `unknown` and its view floor is nought (0290). That nought is
96
+ * indistinguishable from a page nothing has opened, so this order published
97
+ * *nothing reported a view of this version* about a window holding every
98
+ * reader of both forms — and it published it beside a door row that **sums**
99
+ * those forms' arrivals (0299), so the row said five hundred readers arrived
100
+ * at a page nobody read.
101
+ *
102
+ * Checked before `unread`, because it is that nought's cause. It is a fault
103
+ * in the asking rather than in the deployment, and the only standing here
104
+ * that is: split the window by audience (`byAudience`) and read each form on
105
+ * its own, and the page takes its place in the order twice.
106
+ */
107
+ | "unsplit"
108
+ /**
109
+ * There is no page-view row at the door for this revision, so its loss cannot
110
+ * be put on the same scale as another page's.
111
+ *
112
+ * Not a page that was not measured. Its own reading is as good as any other's
113
+ * and every figure inside it stands; what is missing is the one number that
114
+ * makes two pages comparable.
115
+ */
116
+ | "unscaled"
117
+ /**
118
+ * The door row is there and nothing in it says a page view ever began.
119
+ *
120
+ * Either nobody has read this revision, or the senders are not marking their
121
+ * openings — which the page-view reading publishes both numbers for, so the
122
+ * diagnosis is a subtraction a surface can make.
123
+ */
124
+ | "unopened"
125
+ /**
126
+ * It reports more readers lost at one fall than the door has ever seen
127
+ * appear, which no rollup produces.
128
+ *
129
+ * A reading assembled by hand or by a sender that is not one. The scaled
130
+ * figure is withheld because it is the one the disagreement makes absurd, and
131
+ * the fall it was taken from is published so the disagreement can be seen.
132
+ */
133
+ | "inconsistent";
134
+ export declare const DEPLOYMENT_SILENCES: readonly DeploymentSilence[];
135
+ /** Where one page stands in the order, or why it is not in it. */
136
+ export type RankStanding =
137
+ /** In the order, with a fall and a scale for it. */
138
+ "ranked"
139
+ /**
140
+ * Read, scalable, and losing nobody anywhere on the page.
141
+ *
142
+ * The cheerful answer, and a thin window can produce it as well: a revision
143
+ * two readers saw through to the end has no fall in it either. `views` is what
144
+ * tells the two apart and it travels with the row.
145
+ */
146
+ | "unbroken" | DeploymentSilence;
147
+ export declare const RANK_STANDINGS: readonly RankStanding[];
148
+ /** One line per standing, for a surface naming why a page is where it is. */
149
+ export declare const describeRankStanding: (standing: RankStanding) => string;
150
+ /** One revision of one page, as the order has it. */
151
+ export type RankedPage = {
152
+ readonly treeId: TreeId;
153
+ readonly revision: number;
154
+ /**
155
+ * The audience this row is about, or `null` where the reading named none.
156
+ *
157
+ * Two forms of one page stand here as two rows, for the reason two revisions
158
+ * of one tree do (0250): both are live, both have readers, and an order that
159
+ * showed one of them would be hiding a page a deployment is serving. Nothing
160
+ * is summed across them — a reader of one form is not a reader of the other,
161
+ * and the two rows' losses are losses from two populations.
162
+ */
163
+ readonly audienceId: AudienceId | null;
164
+ readonly standing: RankStanding;
165
+ /**
166
+ * The window's view floor, carried through from the reading unchanged.
167
+ *
168
+ * A floor and not a count, which is why it is never the denominator of
169
+ * anything here.
170
+ */
171
+ readonly views: number;
172
+ /**
173
+ * Page views counted at the door, exact, or `null` where this revision has no
174
+ * row.
175
+ *
176
+ * The weight behind the row: *three hundred and forty of twelve hundred
177
+ * readers*, where the second number is this and the first is scaled to it.
178
+ */
179
+ readonly opened: number | null;
180
+ /** This page's own straddle rate, which is what scales its loss. */
181
+ readonly inflation: number | null;
182
+ /** The sharpest fall on the page, where it has one. */
183
+ readonly at: ReadingStop | null;
184
+ /** Readers lost at that fall, as the window's counters have it. */
185
+ readonly lost: number | null;
186
+ /**
187
+ * The same loss on the door's scale, which is the key the order is on.
188
+ *
189
+ * Not a count of people and not rounded into one. Withheld where the page has
190
+ * no fall, no reading, or no row to scale it by.
191
+ */
192
+ readonly readers: number | null;
193
+ /**
194
+ * The fall as a share of the readers who reached the part before it, carried
195
+ * through unchanged.
196
+ *
197
+ * Sound without any correction, because both of its counts come off the same
198
+ * rows — so it is published even for a page whose scaled figure is withheld
199
+ * as inconsistent.
200
+ */
201
+ readonly share: number | null;
202
+ };
203
+ /** A deployment's pages, in the order they should be looked at. */
204
+ export type DeploymentReading = {
205
+ /**
206
+ * Every page with a fall and a scale for it, worst first.
207
+ *
208
+ * Most readers lost at the door's scale, then the larger share, then by tree
209
+ * id and newest revision first — so two pages that lose the same do not
210
+ * reorder on a refresh.
211
+ */
212
+ readonly ranked: readonly RankedPage[];
213
+ /** Every other page, by tree id and newest revision first. */
214
+ readonly unranked: readonly RankedPage[];
215
+ /** The head of the order, which is the page to fix first. */
216
+ readonly worst: RankedPage | null;
217
+ /** How many pages stand in each state, over the ranked and the unranked alike. */
218
+ readonly standings: Readonly<Record<RankStanding, number>>;
219
+ /**
220
+ * Distinct trees across every page read, which is not the number of pages.
221
+ *
222
+ * Two revisions of one tree are two live versions of one page, and both are
223
+ * in the order rather than one replacing the other: a revision shipped an
224
+ * hour ago with four readers on it does not supersede the one that nine
225
+ * thousand read.
226
+ */
227
+ readonly trees: number;
228
+ /**
229
+ * Page views counted at the door across the pages handed in, added.
230
+ *
231
+ * Exact and addable, for the reason no other figure here is: a page view began
232
+ * on one revision of one tree and was counted once. It is a weight rather than
233
+ * a deployment total — this sees the pages its caller read, not the
234
+ * deployment's.
235
+ */
236
+ readonly arrivals: number;
237
+ /**
238
+ * Readings of a revision beyond the first, which were dropped.
239
+ *
240
+ * A caller that concatenated two reads holds one page twice, and a page twice
241
+ * in an order is the one way an order can lie about how much there is to fix.
242
+ */
243
+ readonly duplicated: number;
244
+ /**
245
+ * Door rows for one revision beyond the first, which were ignored.
246
+ *
247
+ * A store keeps one row per revision, so this is a caller's two reads again —
248
+ * and adding them would double a page's arrivals and halve its scaled loss.
249
+ */
250
+ readonly duplicatedRows: number;
251
+ };
252
+ /**
253
+ * A deployment's pages, in the order they should be looked at.
254
+ *
255
+ * Takes the readings rather than the counters, for the reason every derived
256
+ * reading in this subsystem does: the falls and the standings are what this is
257
+ * made of, and deriving them twice is how two screens come to disagree. A
258
+ * caller with counters and trees reads the parts, then the progress, then this.
259
+ *
260
+ * The rows are the whole window of page-view rows a deployment holds, not one
261
+ * page's — each page's own row is picked out of them by the published rule, so
262
+ * no caller writes the matching itself.
263
+ */
264
+ export declare const deploymentReadingOf: (pages: readonly ReadingProgress[], rows: readonly StoredPageViews[]) => DeploymentReading;
265
+ //# sourceMappingURL=deployment.d.ts.map
@@ -0,0 +1,152 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { audienceScopeRead, readingKeyOf } from "./audiences.js";
3
+ import { pageViewsFor } from "./page-views.js";
4
+ export const DEPLOYMENT_SILENCES = everyMemberOf()([
5
+ "unread",
6
+ "unsplit",
7
+ "unscaled",
8
+ "unopened",
9
+ "inconsistent",
10
+ ]);
11
+ export const RANK_STANDINGS = everyMemberOf()([
12
+ "ranked",
13
+ "unbroken",
14
+ "unread",
15
+ "unsplit",
16
+ "unscaled",
17
+ "unopened",
18
+ "inconsistent",
19
+ ]);
20
+ /** One line per standing, for a surface naming why a page is where it is. */
21
+ export const describeRankStanding = (standing) => {
22
+ switch (standing) {
23
+ case "ranked":
24
+ return "in the order, by the readers it loses at its sharpest fall";
25
+ case "unbroken":
26
+ return "read, and losing nobody anywhere on the page";
27
+ case "unread":
28
+ return "nothing reported a view of this version in the window";
29
+ case "unsplit":
30
+ return "one window holds two forms of the page and says which readers neither";
31
+ case "unscaled":
32
+ return "no page views counted at the door, so its loss is not comparable with another page's";
33
+ case "unopened":
34
+ return "the page-view row is there and nothing has said a page view began";
35
+ case "inconsistent":
36
+ return "it loses more readers at one fall than have ever appeared";
37
+ }
38
+ };
39
+ const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(RANK_STANDINGS.map((standing) => [standing, 0])));
40
+ /**
41
+ * One page's row, with the four reasons tried in the order they have to be
42
+ * tried in.
43
+ *
44
+ * `views` before the door, because *nobody read it* is a better answer than
45
+ * *its readers could not be scaled*. The door before the fall, because a page
46
+ * with no scale has nothing to put its fall on. And the disagreement last,
47
+ * because it is a statement about a fall and a row together.
48
+ */
49
+ const rowOf = (page, door) => {
50
+ const where = {
51
+ treeId: page.treeId,
52
+ revision: page.revision,
53
+ audienceId: page.audienceId,
54
+ views: page.views,
55
+ opened: door?.opened ?? null,
56
+ inflation: door?.inflation ?? null,
57
+ };
58
+ const nothing = { at: null, lost: null, readers: null, share: null };
59
+ /**
60
+ * Before the view floor, because a reading read as neither population
61
+ * publishes that floor as nought with full counters behind it, and *nobody
62
+ * read this page* is then a false sentence over a door row that sums both
63
+ * forms' arrivals (0301).
64
+ */
65
+ if (audienceScopeRead(page).reading === "mixed") {
66
+ return { ...where, ...nothing, standing: "unsplit" };
67
+ }
68
+ if (page.views === 0)
69
+ return { ...where, ...nothing, standing: "unread" };
70
+ if (door === null)
71
+ return { ...where, ...nothing, standing: "unscaled" };
72
+ /**
73
+ * A null inflation is exactly an opened of nought — the page-view reading
74
+ * withholds the fraction rather than dividing by nothing — so the check is
75
+ * written on the figure the scale needs and not on the count behind it.
76
+ */
77
+ if (door.inflation === null)
78
+ return { ...where, ...nothing, standing: "unopened" };
79
+ const at = page.steepest;
80
+ if (at === null)
81
+ return { ...where, ...nothing, standing: "unbroken" };
82
+ if (at.lost > door.appearances) {
83
+ return { ...where, standing: "inconsistent", at, lost: at.lost, readers: null, share: at.share };
84
+ }
85
+ return {
86
+ ...where,
87
+ standing: "ranked",
88
+ at,
89
+ lost: at.lost,
90
+ readers: at.lost / (1 + door.inflation),
91
+ share: at.share,
92
+ };
93
+ };
94
+ /**
95
+ * The worse of two, which is the ranking rule spelled once.
96
+ *
97
+ * By readers lost before share, for the reason a single page ranks its own falls
98
+ * that way: a page two readers out of three abandoned is a worse rate and a
99
+ * smaller problem than one four hundred out of a thousand left.
100
+ */
101
+ const worseOf = (one, other) => (other.readers ?? 0) - (one.readers ?? 0) ||
102
+ (other.share ?? 0) - (one.share ?? 0) ||
103
+ one.treeId.localeCompare(other.treeId) ||
104
+ other.revision - one.revision;
105
+ /** Tree id, then newest revision first, which is the order the page-view rows are read in. */
106
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) ||
107
+ other.revision - one.revision ||
108
+ (one.audienceId ?? "").localeCompare(other.audienceId ?? "");
109
+ /**
110
+ * A deployment's pages, in the order they should be looked at.
111
+ *
112
+ * Takes the readings rather than the counters, for the reason every derived
113
+ * reading in this subsystem does: the falls and the standings are what this is
114
+ * made of, and deriving them twice is how two screens come to disagree. A
115
+ * caller with counters and trees reads the parts, then the progress, then this.
116
+ *
117
+ * The rows are the whole window of page-view rows a deployment holds, not one
118
+ * page's — each page's own row is picked out of them by the published rule, so
119
+ * no caller writes the matching itself.
120
+ */
121
+ export const deploymentReadingOf = (pages, rows) => {
122
+ const seen = new Set();
123
+ const read = [];
124
+ let duplicated = 0;
125
+ let duplicatedRows = 0;
126
+ for (const page of pages) {
127
+ const key = readingKeyOf(page);
128
+ if (seen.has(key)) {
129
+ duplicated += 1;
130
+ continue;
131
+ }
132
+ seen.add(key);
133
+ const door = pageViewsFor(page, rows);
134
+ duplicatedRows += door.duplicated;
135
+ read.push(rowOf(page, door.measured));
136
+ }
137
+ const ranked = read.filter((row) => row.standing === "ranked").sort(worseOf);
138
+ const standings = { ...EMPTY_STANDINGS };
139
+ for (const row of read)
140
+ standings[row.standing] += 1;
141
+ return {
142
+ ranked,
143
+ unranked: read.filter((row) => row.standing !== "ranked").sort(byPage),
144
+ worst: ranked[0] ?? null,
145
+ standings,
146
+ trees: new Set(read.map((row) => row.treeId)).size,
147
+ arrivals: read.reduce((sum, row) => sum + (row.opened ?? 0), 0),
148
+ duplicated,
149
+ duplicatedRows,
150
+ };
151
+ };
152
+ //# sourceMappingURL=deployment.js.map