@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,361 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { pageActionOf } from "./action.js";
3
+ import { readingKeyOf } from "./audiences.js";
4
+ import { pageViewsFor } from "./page-views.js";
5
+ /**
6
+ * Whether what a deployment collected can be trusted, and which of its pages
7
+ * cannot.
8
+ *
9
+ * Every reading in this subsystem answers a question about readers and, beside
10
+ * the answer, names the reasons the answer may be absent: a part with no
11
+ * denominator, a window with no page views, a sender that is not marking its
12
+ * openings. Twelve vocabularies of them
13
+ * ([0240](../../decisions/0240-a-silence-is-a-condition-and-a-subject-and-the-two-names-for-one-state-were-not-synonyms.md)),
14
+ * each published beside the figure it withholds.
15
+ *
16
+ * **So a deployment could only discover that its measurement was broken by
17
+ * asking a question about reading and noticing the answer was missing.** Three
18
+ * of those reasons are faults rather than quiet windows — senders that never
19
+ * mark an opening, so every rate on the page has no exact denominator (0229);
20
+ * senders that credit no action to any reader, so every band reads *untouched*
21
+ * while the counters look healthy
22
+ * ([0242](../../decisions/0242-what-readers-did-is-a-share-off-one-row-and-a-leaf-has-no-inside.md));
23
+ * a rollup window shorter than a visit, so every count against the revision is
24
+ * half again the truth
25
+ * ([0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)).
26
+ * Each of them is page by page, one card at a time, and a deployment with
27
+ * forty pages and one broken sender had no way to be told.
28
+ *
29
+ * This is that answer, taken off the readings and the door rows a deployment
30
+ * already has and nothing else: no payload, no browser change, no counter that
31
+ * does not exist, no column and no byte on any wire.
32
+ *
33
+ * ## A fault is named by what it costs, and the remedy is named only where the
34
+ * rows determine one
35
+ *
36
+ * The six faults here are not six shapes of missing data; they are six
37
+ * different things to go and do, and the reason to report them together is that
38
+ * a person looking at a reader screen cannot tell them apart from the figures.
39
+ * {@link remedyOf} publishes which of four hands each one falls to — the pages,
40
+ * the configuration, the caller — and `undetermined` where the rows genuinely do
41
+ * not say, which is one fault out of six and is better than inventing one of
42
+ * three causes.
43
+ *
44
+ * ## What a fault costs is the page's arrivals, and a page is counted once
45
+ *
46
+ * The readers a fault affects are the readers of the page it is on: a sender not
47
+ * marking its openings spoils every rate on that revision, not some share of
48
+ * them. So the cost is the page's own `opened` — exact, counted once at the
49
+ * door, and addable for the reason no other counter here is (0219).
50
+ *
51
+ * **Which makes the only double-count available to this reading the one it
52
+ * guards: a page counted once per fault it has.** A revision with three faults
53
+ * is one revision and its readers are added once, because counting a window and
54
+ * forgetting it are one operation
55
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
56
+ * {@link CollectionHealth.faults} counts revisions per fault and so deliberately
57
+ * does not add to the number of faulted pages, which is said on the field.
58
+ *
59
+ * ## A page the door cannot price is not ranked against one it can
60
+ *
61
+ * A revision whose counters hold readers and whose door row is missing is the
62
+ * first fault in the list, and it is also the one page whose cost cannot be
63
+ * stated: there is no exact arrival count to rank it by. Ranking it by its view
64
+ * floor would put it in the order at a height taken off a different scale, which
65
+ * is the mixing
66
+ * [0265](../../decisions/0265-what-readers-do-inside-a-kind-of-part-is-a-share-of-the-readers-who-met-it-and-the-door-is-only-a-weight.md)
67
+ * refuses one unit across and
68
+ * [0250](../../decisions/0250-a-deployment-is-ordered-by-readers-lost-at-the-doors-scale-and-a-page-the-door-cannot-scale-is-out-of-the-order.md)
69
+ * refuses for an order of pages. So it is published apart, in
70
+ * {@link CollectionHealth.unpriced}, with its floor on the row and never in the
71
+ * ranking.
72
+ *
73
+ * ## What is published as a figure rather than judged
74
+ *
75
+ * **Openings no rollup has folded, where nothing says when a fold last was.**
76
+ * `pending` is *the other sign of the same subtraction* (0219) and is what a
77
+ * stalled collection looks like — and it is also what a revision published two
78
+ * minutes ago looks like, because the ordinary lag of the tallies behind the
79
+ * buffer is one window
80
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
81
+ * `updatedAt` cannot tell those apart, because the door writes it on every
82
+ * delivery: a busy page whose rollup has stopped keeps a fresh timestamp while
83
+ * its appearances never move.
84
+ *
85
+ * A page-view row now carries `foldedAt`, written by the fold and by nothing
86
+ * else ([0274](../../decisions/0274-a-page-view-row-says-when-the-fold-last-touched-it-and-a-stall-is-judged-against-a-schedule-the-deployment-hands-in.md)),
87
+ * so the lag is readable — against a schedule the caller hands in, because how
88
+ * long a fold may honestly be behind is the deployment's own cron interval and
89
+ * rollup window and is not the framework's to assume. Hand one in and
90
+ * `collection-stalled` is raised on the pages whose openings have waited longer
91
+ * than that. Hand none in, or read a row no fold has ever touched, and nothing
92
+ * is claimed: `pending` is published per page and added across the deployment,
93
+ * {@link CollectionHealth.unattested} counts the revisions whose lag could not
94
+ * be read at all, and no fault is raised from either.
95
+ *
96
+ * Pure, linear in the readings times the rows, and reaches no store, clock or
97
+ * DOM.
98
+ */
99
+ /**
100
+ * How generous a revision's distinct counts may be before its absolute figures
101
+ * are not worth printing.
102
+ *
103
+ * `drift ÷ opened` above a half means the appearances are more than one and a
104
+ * half times the openings — so the typical page view is being folded into more
105
+ * than one and a half rollup windows, which is a window shorter than the reading
106
+ * it measures. Every **ratio** in this subsystem survives that, because both of
107
+ * its counts come off the same rows and the inflation very nearly divides out
108
+ * (0221, 0229, 0242); every **count** on a card is half again what it should be.
109
+ *
110
+ * Published and not overridable, which is
111
+ * [0218](../../decisions/0218-what-a-counter-means-is-published-and-the-browser-pays-for-the-number-and-not-its-name.md)'s
112
+ * rule at the one remove where it still holds: how much error makes a figure
113
+ * unfit to print is the framework's statement about its own numbers, where the
114
+ * remedy — a longer window — is the deployment's own configuration.
115
+ */
116
+ export const COUNTS_INFLATED_ABOVE = 0.5;
117
+ export const COLLECTION_FAULTS = everyMemberOf()([
118
+ "door-unscaled",
119
+ "openings-unmarked",
120
+ "counts-inflated",
121
+ "collection-stalled",
122
+ "actions-uncredited",
123
+ "rows-mishandled",
124
+ "audiences-mixed",
125
+ ]);
126
+ /** One line per fault, for a surface naming what is wrong. */
127
+ export const describeCollectionFault = (fault) => {
128
+ switch (fault) {
129
+ case "door-unscaled":
130
+ return "readers were counted against this version and no page views were counted at its door";
131
+ case "openings-unmarked":
132
+ return "page views of this version appeared in a rollup and nothing said one began";
133
+ case "counts-inflated":
134
+ return "the rollup window is shorter than the visits, so every count against this version is high";
135
+ case "collection-stalled":
136
+ return "page views of this version have been waiting longer than a fold is meant to take";
137
+ case "actions-uncredited":
138
+ return "readers acted on this page and no reader was credited with acting inside anything";
139
+ case "rows-mishandled":
140
+ return "rows were handed in that this version cannot account for, or handed in twice";
141
+ case "audiences-mixed":
142
+ return "this page was served to more than one audience and the window holding both was read as one";
143
+ }
144
+ };
145
+ export const FAULT_REMEDIES = everyMemberOf()([
146
+ "senders",
147
+ "configuration",
148
+ "caller",
149
+ "undetermined",
150
+ ]);
151
+ /** Whose hand this fault falls to, which is the half of a fault a person acts on. */
152
+ export const remedyOf = (fault) => {
153
+ switch (fault) {
154
+ case "door-unscaled":
155
+ return "undetermined";
156
+ case "openings-unmarked":
157
+ return "senders";
158
+ case "counts-inflated":
159
+ return "configuration";
160
+ case "collection-stalled":
161
+ return "configuration";
162
+ case "actions-uncredited":
163
+ return "senders";
164
+ case "rows-mishandled":
165
+ return "caller";
166
+ case "audiences-mixed":
167
+ return "caller";
168
+ }
169
+ };
170
+ export const HEALTH_STANDINGS = everyMemberOf()([
171
+ "sound",
172
+ "faulted",
173
+ "unmeasured",
174
+ "unfolded",
175
+ ]);
176
+ /** One line per standing, for a surface saying why a page is where it is. */
177
+ export const describeHealthStanding = (standing) => {
178
+ switch (standing) {
179
+ case "sound":
180
+ return "measured, with nothing these rows can see wrong with it";
181
+ case "faulted":
182
+ return "something about what is being collected here is wrong";
183
+ case "unmeasured":
184
+ return "nothing was collected about this version in the window";
185
+ case "unfolded":
186
+ return "page views began and no rollup has folded any of them yet, and nothing here says that is late";
187
+ }
188
+ };
189
+ const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(HEALTH_STANDINGS.map((standing) => [standing, 0])));
190
+ const EMPTY_FAULTS = Object.freeze(Object.fromEntries(COLLECTION_FAULTS.map((fault) => [fault, 0])));
191
+ /**
192
+ * Whether this revision's openings have waited longer than a fold is meant to
193
+ * take.
194
+ *
195
+ * **Four states answer *no* without anything being sound**, and each of them is
196
+ * a refusal rather than a gap:
197
+ *
198
+ * - **no schedule.** How long a fold may be behind is the deployment's cron
199
+ * interval plus its ripeness window, and a framework that supplied a default
200
+ * would fault an hourly collection for not being a ten-minute one.
201
+ * - **nothing pending.** A collection that has stopped where nobody is arriving
202
+ * is costing no reader's measurement anything, and there is nothing waiting
203
+ * for it to be late for.
204
+ * - **no fold attested.** A row written before `folded_at` existed, or one no
205
+ * fold has touched, says *nothing here can tell you* — and it reads exactly
206
+ * like a brand-new revision (0274).
207
+ * - **a schedule that is not a positive, finite number of milliseconds, or an
208
+ * instant that does not parse.** A nought allowance would make the lag the
209
+ * design requires into a fault on every live page.
210
+ *
211
+ * A fold timestamp ahead of the instant handed in is a clock disagreeing with
212
+ * itself, and it answers *no* by the same subtraction rather than by a special
213
+ * case: a negative age is never longer than a positive allowance.
214
+ *
215
+ * **A door summed over two forms is stalled exactly when one of its forms is**,
216
+ * and that equivalence is a property of the fold the reading waits on rather
217
+ * than of anything here: `pending` is the sum of the forms' pending openings
218
+ * and `foldedAt` is the oldest fold attested by a form that still has some
219
+ * (0299), so one lagging form answers *yes* and a quiet form whose openings are
220
+ * all folded cannot.
221
+ */
222
+ const stalled = (door, schedule) => {
223
+ if (door === null || schedule === undefined)
224
+ return false;
225
+ if (door.pending <= 0 || door.foldedAt === undefined)
226
+ return false;
227
+ if (!Number.isFinite(schedule.foldsWithinMs) || schedule.foldsWithinMs <= 0)
228
+ return false;
229
+ const at = Date.parse(schedule.at);
230
+ const folded = Date.parse(door.foldedAt);
231
+ if (Number.isNaN(at) || Number.isNaN(folded))
232
+ return false;
233
+ return at - folded > schedule.foldsWithinMs;
234
+ };
235
+ /**
236
+ * One revision's row, with every fault it has rather than the first one found.
237
+ *
238
+ * A page with an old sender and a short window has two things to do and a
239
+ * reading that stopped at the first would hide the second behind a fix.
240
+ */
241
+ const healthOf = (reading, door, doubledRows, schedule) => {
242
+ const doubled = reading.duplicated.length + doubledRows;
243
+ const faults = [];
244
+ if (reading.views > 0 && door === null)
245
+ faults.push("door-unscaled");
246
+ if (door !== null && door.opened === 0 && (door.appearances > 0 || reading.views > 0)) {
247
+ faults.push("openings-unmarked");
248
+ }
249
+ if (door !== null && door.inflation !== null && door.inflation > COUNTS_INFLATED_ABOVE) {
250
+ faults.push("counts-inflated");
251
+ }
252
+ if (stalled(door, schedule))
253
+ faults.push("collection-stalled");
254
+ if (pageActionOf(reading).unwalked)
255
+ faults.push("actions-uncredited");
256
+ if (reading.orphaned.length > 0 || doubled > 0)
257
+ faults.push("rows-mishandled");
258
+ if (reading.audienceId === null && reading.audiences.length > 1)
259
+ faults.push("audiences-mixed");
260
+ const standing = faults.length > 0
261
+ ? "faulted"
262
+ : reading.views > 0
263
+ ? "sound"
264
+ : door !== null && door.opened > 0
265
+ ? "unfolded"
266
+ : "unmeasured";
267
+ return {
268
+ treeId: reading.treeId,
269
+ revision: reading.revision,
270
+ audienceId: reading.audienceId,
271
+ standing,
272
+ faults,
273
+ views: reading.views,
274
+ arrivals: door?.opened ?? null,
275
+ appearances: door?.appearances ?? null,
276
+ inflation: door?.inflation ?? null,
277
+ pending: door?.pending ?? 0,
278
+ foldedAt: door?.foldedAt ?? null,
279
+ orphaned: reading.orphaned.length,
280
+ doubled,
281
+ };
282
+ };
283
+ /**
284
+ * The worse of two faulted pages, which is the ranking rule spelled once.
285
+ *
286
+ * By arrivals before the view floor, because the arrivals are the readers and
287
+ * the floor is only what is left to order by when two pages cost the same.
288
+ */
289
+ const worseOf = (one, other) => (other.arrivals ?? 0) - (one.arrivals ?? 0) ||
290
+ other.views - one.views ||
291
+ one.treeId.localeCompare(other.treeId) ||
292
+ other.revision - one.revision;
293
+ /**
294
+ * Tree id, then newest revision first, which is the order the door rows are
295
+ * read in, then the audience — which only separates two rows that are the same
296
+ * page in two forms, and is there so the order is total rather than left to
297
+ * the input's.
298
+ */
299
+ const byPage = (one, other) => one.treeId.localeCompare(other.treeId) ||
300
+ other.revision - one.revision ||
301
+ (one.audienceId ?? "").localeCompare(other.audienceId ?? "");
302
+ /**
303
+ * What a deployment is collecting, read off the page readings and the door rows
304
+ * it already has.
305
+ *
306
+ * Takes the readings rather than the counters, as every derived reading here
307
+ * does: the join to the tree is what makes an orphaned counter and an uncredited
308
+ * action visible at all, and deriving it twice is how two screens come to
309
+ * disagree. A caller with counters and trees reads the parts, then this.
310
+ *
311
+ * The rows are the whole window of door rows a deployment holds, not one page's
312
+ * — each revision's own row is picked out of them by the published rule (0219),
313
+ * so no caller writes the matching itself.
314
+ *
315
+ * The schedule is optional and is the only argument here that is not a row: a
316
+ * caller that states what its collection promises gets `collection-stalled`
317
+ * judged for it, and one that does not gets every other fault and `pending`
318
+ * published unjudged (0274).
319
+ */
320
+ export const collectionHealthOf = (readings, rows, schedule) => {
321
+ const seen = new Set();
322
+ const pages = [];
323
+ let duplicated = 0;
324
+ for (const reading of readings) {
325
+ const key = readingKeyOf(reading);
326
+ if (seen.has(key)) {
327
+ duplicated += 1;
328
+ continue;
329
+ }
330
+ seen.add(key);
331
+ const door = pageViewsFor(reading, rows);
332
+ pages.push(healthOf(reading, door.measured, door.duplicated, schedule));
333
+ }
334
+ const standings = { ...EMPTY_STANDINGS };
335
+ const faults = { ...EMPTY_FAULTS };
336
+ for (const page of pages) {
337
+ standings[page.standing] += 1;
338
+ for (const fault of page.faults)
339
+ faults[fault] += 1;
340
+ }
341
+ const faulted = pages
342
+ .filter((page) => page.standing === "faulted" && page.arrivals !== null)
343
+ .sort(worseOf);
344
+ return {
345
+ pages: [...pages].sort(byPage),
346
+ faulted,
347
+ unpriced: pages
348
+ .filter((page) => page.standing === "faulted" && page.arrivals === null)
349
+ .sort(byPage),
350
+ worst: faulted[0] ?? null,
351
+ standings,
352
+ faults,
353
+ readersAffected: faulted.reduce((sum, page) => sum + (page.arrivals ?? 0), 0),
354
+ arrivals: pages.reduce((sum, page) => sum + (page.arrivals ?? 0), 0),
355
+ pending: pages.reduce((sum, page) => sum + page.pending, 0),
356
+ unattested: pages.filter((page) => page.pending > 0 && page.foldedAt === null).length,
357
+ trees: new Set(pages.map((page) => page.treeId)).size,
358
+ duplicated,
359
+ };
360
+ };
361
+ //# sourceMappingURL=health.js.map
@@ -16,16 +16,57 @@
16
16
  * `@jam-overture/loom/signals/postgres` is where a deployment picks it up, exactly
17
17
  * as the store and the journal do it.
18
18
  */
19
+ export * from "./action-change.js";
20
+ export * from "./action.js";
21
+ export * from "./arriving.js";
22
+ export * from "./audiences.js";
19
23
  export * from "./broadcast.js";
24
+ export * from "./change.js";
20
25
  export * from "./collect.js";
26
+ export * from "./copy-change.js";
27
+ export * from "./copy.js";
21
28
  export * from "./deliver.js";
29
+ export * from "./deployment-change.js";
30
+ export * from "./deployment.js";
31
+ export * from "./door.js";
22
32
  export * from "./fold.js";
33
+ export * from "./form-action.js";
34
+ export * from "./form-copy.js";
35
+ export * from "./forms.js";
36
+ export * from "./funnel-change.js";
37
+ export * from "./funnel.js";
38
+ export * from "./health.js";
23
39
  export * from "./ingest.js";
24
40
  export * from "./intake.js";
25
41
  export * from "./journal.js";
42
+ export * from "./library-action.js";
43
+ export * from "./library-change.js";
44
+ export * from "./library-copy-change.js";
45
+ export * from "./library-pace.js";
46
+ export * from "./library-reach-change.js";
47
+ export * from "./library-reach.js";
48
+ export * from "./library-word-reach-change.js";
49
+ export * from "./library.js";
26
50
  export * from "./memory.js";
51
+ export * from "./notice.js";
52
+ export * from "./pace-change.js";
53
+ export * from "./pace.js";
54
+ export * from "./page-views.js";
55
+ export * from "./parts.js";
56
+ export * from "./progress.js";
57
+ export * from "./ratios.js";
58
+ export * from "./reach.js";
59
+ export * from "./readership.js";
60
+ export * from "./readable.js";
61
+ export * from "./region-pages.js";
62
+ export * from "./region.js";
63
+ export * from "./retention.js";
27
64
  export * from "./rollup.js";
28
65
  export * from "./signal.js";
66
+ export * from "./silence-census.js";
67
+ export * from "./silences.js";
29
68
  export * from "./tally.js";
30
69
  export * from "./view.js";
70
+ export * from "./window-figures.js";
71
+ export * from "./window.js";
31
72
  //# sourceMappingURL=index.d.ts.map
@@ -16,16 +16,57 @@
16
16
  * `@jam-overture/loom/signals/postgres` is where a deployment picks it up, exactly
17
17
  * as the store and the journal do it.
18
18
  */
19
+ export * from "./action-change.js";
20
+ export * from "./action.js";
21
+ export * from "./arriving.js";
22
+ export * from "./audiences.js";
19
23
  export * from "./broadcast.js";
24
+ export * from "./change.js";
20
25
  export * from "./collect.js";
26
+ export * from "./copy-change.js";
27
+ export * from "./copy.js";
21
28
  export * from "./deliver.js";
29
+ export * from "./deployment-change.js";
30
+ export * from "./deployment.js";
31
+ export * from "./door.js";
22
32
  export * from "./fold.js";
33
+ export * from "./form-action.js";
34
+ export * from "./form-copy.js";
35
+ export * from "./forms.js";
36
+ export * from "./funnel-change.js";
37
+ export * from "./funnel.js";
38
+ export * from "./health.js";
23
39
  export * from "./ingest.js";
24
40
  export * from "./intake.js";
25
41
  export * from "./journal.js";
42
+ export * from "./library-action.js";
43
+ export * from "./library-change.js";
44
+ export * from "./library-copy-change.js";
45
+ export * from "./library-pace.js";
46
+ export * from "./library-reach-change.js";
47
+ export * from "./library-reach.js";
48
+ export * from "./library-word-reach-change.js";
49
+ export * from "./library.js";
26
50
  export * from "./memory.js";
51
+ export * from "./notice.js";
52
+ export * from "./pace-change.js";
53
+ export * from "./pace.js";
54
+ export * from "./page-views.js";
55
+ export * from "./parts.js";
56
+ export * from "./progress.js";
57
+ export * from "./ratios.js";
58
+ export * from "./reach.js";
59
+ export * from "./readership.js";
60
+ export * from "./readable.js";
61
+ export * from "./region-pages.js";
62
+ export * from "./region.js";
63
+ export * from "./retention.js";
27
64
  export * from "./rollup.js";
28
65
  export * from "./signal.js";
66
+ export * from "./silence-census.js";
67
+ export * from "./silences.js";
29
68
  export * from "./tally.js";
30
69
  export * from "./view.js";
70
+ export * from "./window-figures.js";
71
+ export * from "./window.js";
31
72
  //# sourceMappingURL=index.js.map
@@ -1,6 +1,8 @@
1
1
  import { type Result } from "../result.js";
2
2
  import type { ReaderSignalJournal, ReaderSignalStoreError } from "./journal.js";
3
+ import { type ReaderRegion, type ReaderRegionStore } from "./region.js";
3
4
  import { type ReaderSignalParseError } from "./signal.js";
5
+ import type { ReaderOpeningCounter } from "./tally.js";
4
6
  /**
5
7
  * The doorway a browser's batches come through.
6
8
  *
@@ -27,6 +29,59 @@ export declare const MAX_BATCHES_PER_DELIVERY = 50;
27
29
  export type IngestOutcome = {
28
30
  readonly batches: number;
29
31
  readonly signals: number;
32
+ /**
33
+ * Page views this delivery opened, which is what the exact counter moved by.
34
+ *
35
+ * Zero unless the caller keeps that counter and the delivery actually opened
36
+ * something — most deliveries of a page view are the middle of one.
37
+ */
38
+ readonly opened: number;
39
+ /**
40
+ * Page views counted against a region, which is zero unless the caller said
41
+ * where the delivery came from and the delivery opened a page view.
42
+ */
43
+ readonly regions: number;
44
+ /**
45
+ * Why a counter did not move, when a store refused it.
46
+ *
47
+ * Present and the delivery still stands: the batch is already kept, and a
48
+ * sender told to retry would deliver it twice, which is the one failure in
49
+ * this subsystem that cannot be undone (0158). So a lost count is a counter
50
+ * that did not move, reported here rather than raised — the same trade a sink
51
+ * makes when a browser refuses a beacon.
52
+ */
53
+ readonly openingError?: ReaderSignalStoreError;
54
+ readonly regionError?: ReaderSignalStoreError;
55
+ };
56
+ /** Where a delivery came from, and the buckets to count it in. */
57
+ export type RegionCounter = {
58
+ readonly store: ReaderRegionStore;
59
+ readonly region: ReaderRegion;
60
+ };
61
+ /**
62
+ * What this delivery is counted into, besides being buffered.
63
+ *
64
+ * Both of these are read from the request rather than from the batch — the
65
+ * framework has no request and no opinion about which header a platform writes
66
+ * — and both are counted once per page view rather than once per delivery. What
67
+ * the framework owns is that arithmetic: against a counter, never onto the
68
+ * batch that is about to be buffered.
69
+ *
70
+ * Absent means a caller that keeps neither, which is a supported deployment and
71
+ * not a misconfigured one: a buffer and a rollup answer every question except
72
+ * *how many readers* and *from where*.
73
+ */
74
+ export type DoorCounters = {
75
+ /** When, as an instant every counter this delivery moves is stamped with. The caller's clock. */
76
+ readonly at: string;
77
+ /** Where the delivery came from. Absent on a deployment that does not count regions. */
78
+ readonly region?: RegionCounter;
79
+ /**
80
+ * How many page views began. No switch guards it where it is wired, because a
81
+ * count of page views of a revision names nowhere and nobody — it is the
82
+ * denominator everything else is a rate against.
83
+ */
84
+ readonly openings?: ReaderOpeningCounter;
30
85
  };
31
86
  export type IngestError = {
32
87
  readonly code: "invalid-delivery";
@@ -47,5 +102,5 @@ export declare const describeIngestError: (error: IngestError) => string;
47
102
  * neither is something a browser can be asked to work out. It also means the
48
103
  * refusal is actionable: one index, one reason.
49
104
  */
50
- export declare const ingestReaderSignals: (journal: ReaderSignalJournal, input: unknown) => Promise<Result<IngestOutcome, IngestError>>;
105
+ export declare const ingestReaderSignals: (journal: ReaderSignalJournal, input: unknown, counters?: DoorCounters) => Promise<Result<IngestOutcome, IngestError>>;
51
106
  //# sourceMappingURL=ingest.d.ts.map
@@ -1,4 +1,7 @@
1
+ import { DEFAULT_AUDIENCE_ID } from "../audience/audience.js";
1
2
  import { err, ok } from "../result.js";
3
+ import { openingsOf } from "./page-views.js";
4
+ import { regionCountsOf } from "./region.js";
2
5
  import { parseReaderSignalBatch } from "./signal.js";
3
6
  /**
4
7
  * The doorway a browser's batches come through.
@@ -39,6 +42,35 @@ export const describeIngestError = (error) => {
39
42
  * saves every caller an envelope.
40
43
  */
41
44
  const deliveryOf = (input) => (Array.isArray(input) ? input : [input]);
45
+ /**
46
+ * What one counter contributed to the outcome: the page views it moved by, or
47
+ * why it did not move.
48
+ *
49
+ * A refused write reports nought rather than the number it would have added, so
50
+ * a caller adding up what it was told is adding up what is actually stored.
51
+ */
52
+ const moved = (counts, kept) => kept !== undefined && !kept.ok
53
+ ? { views: 0, error: kept.error }
54
+ : { views: counts.reduce((total, count) => total + count.views, 0) };
55
+ /**
56
+ * A delivery's batches, by the audience each was served under (0284).
57
+ *
58
+ * `ReaderSignalBatch.audience` is what the sender said and may be absent, so it
59
+ * is resolved here the way the buffer resolves it — one spelling of *this batch
60
+ * named no audience* rather than two.
61
+ */
62
+ const byAudience = (batches) => {
63
+ const grouped = new Map();
64
+ for (const batch of batches) {
65
+ const audience = batch.audience ?? DEFAULT_AUDIENCE_ID;
66
+ const group = grouped.get(audience);
67
+ if (group === undefined)
68
+ grouped.set(audience, [batch]);
69
+ else
70
+ group.push(batch);
71
+ }
72
+ return grouped;
73
+ };
42
74
  /**
43
75
  * Parse a delivery and keep it.
44
76
  *
@@ -47,7 +79,7 @@ const deliveryOf = (input) => (Array.isArray(input) ? input : [input]);
47
79
  * neither is something a browser can be asked to work out. It also means the
48
80
  * refusal is actionable: one index, one reason.
49
81
  */
50
- export const ingestReaderSignals = async (journal, input) => {
82
+ export const ingestReaderSignals = async (journal, input, counters) => {
51
83
  const delivery = deliveryOf(input);
52
84
  if (delivery.length > MAX_BATCHES_PER_DELIVERY) {
53
85
  return err({ code: "too-many", limit: MAX_BATCHES_PER_DELIVERY, given: delivery.length });
@@ -62,9 +94,67 @@ export const ingestReaderSignals = async (journal, input) => {
62
94
  const received = await journal.receive(batches);
63
95
  if (!received.ok)
64
96
  return err(received.error);
97
+ /**
98
+ * After the buffer accepted it, never before. A page view counted for a
99
+ * delivery the journal then refused would be a reader who arrived and read
100
+ * nothing — every other counter about that page view is missing, and the only
101
+ * numbers that moved are the two about them having turned up.
102
+ *
103
+ * **One walk for both counters.** The openings are found once and a region is
104
+ * a stamp on them, so the two can never disagree about how many readers
105
+ * arrived (`page-views.ts`).
106
+ */
107
+ /**
108
+ * **Per audience, because a counter row belongs to one** (0284).
109
+ *
110
+ * A delivery is normally one page's worth and so one audience's, but nothing
111
+ * in the wire format says it has to be — and filing two audiences' arrivals
112
+ * under one would be the same unrecoverable addition at the door that
113
+ * `collect.ts` avoids at the fold. The walk is still one walk **per
114
+ * audience**, which is what keeps a region a stamp on an opening somebody
115
+ * already counted rather than a second opinion about how many arrived.
116
+ */
117
+ const arrivals = counters === undefined
118
+ ? []
119
+ : [...byAudience(batches)].map(([audience, group]) => {
120
+ const openings = openingsOf(group);
121
+ return {
122
+ audience,
123
+ counting: counters.openings === undefined ? [] : openings,
124
+ counted: counters.region === undefined
125
+ ? []
126
+ : regionCountsOf(openings, counters.region.region),
127
+ };
128
+ });
129
+ const counting = arrivals.flatMap((arrival) => arrival.counting);
130
+ const counted = arrivals.flatMap((arrival) => arrival.counted);
131
+ /**
132
+ * The first failure of each counter is the one reported, and the audiences
133
+ * after it are not attempted: the outcome has room for one error per counter,
134
+ * and a door that went on writing after a store said it was unavailable would
135
+ * be reporting a number it has no reason to believe.
136
+ */
137
+ let openingsKept;
138
+ let regionsKept;
139
+ for (const arrival of arrivals) {
140
+ if (counters?.openings !== undefined &&
141
+ arrival.counting.length > 0 &&
142
+ openingsKept?.ok !== false) {
143
+ openingsKept = await counters.openings.opened(arrival.counting, counters.at, arrival.audience);
144
+ }
145
+ if (counters?.region !== undefined && arrival.counted.length > 0 && regionsKept?.ok !== false) {
146
+ regionsKept = await counters.region.store.count(arrival.counted, counters.at, arrival.audience);
147
+ }
148
+ }
149
+ const opened = moved(counting, openingsKept);
150
+ const regions = moved(counted, regionsKept);
65
151
  return ok({
66
152
  batches: batches.length,
67
153
  signals: batches.reduce((count, batch) => count + batch.signals.length, 0),
154
+ opened: opened.views,
155
+ regions: regions.views,
156
+ ...(opened.error === undefined ? {} : { openingError: opened.error }),
157
+ ...(regions.error === undefined ? {} : { regionError: regions.error }),
68
158
  });
69
159
  };
70
160
  //# sourceMappingURL=ingest.js.map