@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,497 @@
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 { PageReading } from "./parts.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 declare const COUNTS_INFLATED_ABOVE = 0.5;
117
+ /**
118
+ * What a deployment expects of its own collection, which is the one fact here
119
+ * that no row can supply.
120
+ *
121
+ * Nothing in this subsystem schedules a fold: a host calls
122
+ * {@link collectReaderSignals} from a cron, a deploy hook or by hand, and the
123
+ * ripeness window it folds behind is its own configuration (0146, 0158). So
124
+ * *how late is late* is two numbers only the deployment knows, and a framework
125
+ * that guessed would fault a deployment that folds hourly for not folding in
126
+ * ten minutes.
127
+ *
128
+ * Handed in rather than assumed, which is the shape the straddle correction
129
+ * already takes
130
+ * ([0230](../../decisions/0230-a-part-was-read-when-readers-had-time-for-its-words-and-only-the-skim-is-a-safe-claim.md)),
131
+ * and optional, because a caller with no schedule to state should get a reading
132
+ * that judges nothing rather than one that judges against a default.
133
+ */
134
+ export type CollectionSchedule = {
135
+ /**
136
+ * The instant the reading is taken, as an ISO 8601 timestamp.
137
+ *
138
+ * A parameter and never a clock read inside, for the reason every other
139
+ * instant in this subsystem is handed in: a reading that read the wall clock
140
+ * would answer differently on two calls over one set of rows.
141
+ */
142
+ readonly at: string;
143
+ /**
144
+ * The longest a fold may honestly be behind, in milliseconds.
145
+ *
146
+ * The deployment's collection interval **plus** its ripeness window, not the
147
+ * window alone: a batch is not folded until it ripens, and then not until the
148
+ * next run, so the two add. A deployment that folds every hour behind a
149
+ * ten-minute window expects a fold within seventy minutes, and anything
150
+ * shorter handed in here is a fault on a healthy collection.
151
+ *
152
+ * Nothing is judged where this is not a positive, finite number of
153
+ * milliseconds — a nought would call the lag the design *requires* a fault,
154
+ * which is the one way this reading could be made to cry wolf on every page
155
+ * of a healthy deployment.
156
+ */
157
+ readonly foldsWithinMs: number;
158
+ };
159
+ /** Something wrong with what a deployment is collecting, rather than a quiet window. */
160
+ export type CollectionFault =
161
+ /**
162
+ * The window's counters hold readers of this revision and there is no
163
+ * page-view row at the door for it.
164
+ *
165
+ * Every rate on the page is left with the view floor for a denominator, which
166
+ * is short of the page views there were (0212), and nothing on the page can be
167
+ * put on the same scale as another page's (0250).
168
+ *
169
+ * **Three causes and the rows cannot tell them apart:** the revision was
170
+ * served by senders older than the opening marker, the door row has passed out
171
+ * of the deployment's retention window while the counters it describes have
172
+ * not, or the counters were assembled by something that is not a sender. So
173
+ * the remedy is `undetermined` rather than one of the three guessed.
174
+ */
175
+ "door-unscaled"
176
+ /**
177
+ * The door row is there, something counted readers of this revision — a
178
+ * rollup's appearances, or the counters themselves — and nothing has ever
179
+ * said a page view *began*.
180
+ *
181
+ * An honest sender marks at most one batch of each page view as the one that
182
+ * opened it (0214), and a deployment whose senders do not is the deployment a
183
+ * share-of-readers reading calls `unopened` (0229): every rate
184
+ * denominator-less while the counters look perfectly healthy. It is the one
185
+ * fault here whose symptom is invisible on every screen that does not divide
186
+ * by the door.
187
+ */
188
+ | "openings-unmarked"
189
+ /**
190
+ * The revision's distinct counts are inflated past
191
+ * {@link COUNTS_INFLATED_ABOVE}.
192
+ *
193
+ * Not a broken sender and not a broken rollup: a rollup window shorter than
194
+ * the visits being measured, which is the one control a deployment has over
195
+ * this error (0219). The shares stay sound and the counts do not.
196
+ */
197
+ | "counts-inflated"
198
+ /**
199
+ * Page views of this revision are waiting to be folded and the last fold of
200
+ * it was longer ago than the deployment said its collection takes.
201
+ *
202
+ * `pending` openings are the ordinary state of a live page — the lag of the
203
+ * tallies behind the buffer is one window by design (0158) — so the fault is
204
+ * never the pending count itself. It is the **age** of the fold that should
205
+ * have cleared it, read off `foldedAt` and judged against the
206
+ * {@link CollectionSchedule} the caller handed in. Nothing is raised without
207
+ * one, and nothing is raised on a row no fold has ever touched, which is
208
+ * every row of a deployment upgraded past this column until its next run.
209
+ *
210
+ * What it costs is every count on the page: a fold that never comes is
211
+ * counters frozen where they were while the door goes on counting arrivals,
212
+ * so each rate reads lower than the truth by however much reading has
213
+ * happened since. It falls to the same hand as a window that is too short —
214
+ * the deployment's own configuration — because what has stopped is the thing
215
+ * it schedules.
216
+ *
217
+ * **It can hide behind `openings-unmarked`.** A deployment whose senders
218
+ * never mark an opening has nothing pending by construction, so a stall there
219
+ * is invisible until the door is counting again — which is why the marker is
220
+ * the first fault to fix and is published first.
221
+ *
222
+ * **It cannot be true at the same time as `counts-inflated`**, and the reason
223
+ * is arithmetic rather than policy: `drift` and `pending` are the two signs of
224
+ * one subtraction (0219), so a revision whose appearances have outrun its
225
+ * openings has nothing pending to be late. The two faults the same hand
226
+ * answers for are therefore alternatives, which is why they are adjacent in
227
+ * {@link COLLECTION_FAULTS} rather than additive.
228
+ */
229
+ | "collection-stalled"
230
+ /**
231
+ * The window holds uses of this page and credits none of them to a reader.
232
+ *
233
+ * A press is filed against the control and credited to the addressed ancestors
234
+ * the signal carries (0167), so a sender whose delegated signals have no
235
+ * `within` adds occurrences and no `engaged` at all. Taken from
236
+ * {@link pageActionOf} rather than spelled a second time, so the two readings
237
+ * cannot come to disagree about what it looks like (0242).
238
+ */
239
+ | "actions-uncredited"
240
+ /**
241
+ * Counters filed under this tree and revision that name nodes the tree does
242
+ * not contain, or the same row handed in twice.
243
+ *
244
+ * The two faults a **caller** can have rather than a deployment: a tree and a
245
+ * window that do not belong together, which leaves most parts reading
246
+ * `skipped` while the numbers stay plausible (0212), and two reads
247
+ * concatenated instead of one, which neither sums nor overwrites honestly
248
+ * (0147). Published as one fault because the hand it falls to is one hand and
249
+ * the fix is one fix, with both counts on the row.
250
+ */
251
+ | "rows-mishandled"
252
+ /**
253
+ * The window holds two audiences' counters for this page and the reading was
254
+ * taken of neither.
255
+ *
256
+ * A page is one base tree and the deltas an audience earns (0263), so two
257
+ * forms of it produce two sets of counters over one tree at one revision,
258
+ * told apart by one column (0284) and by nothing else. A reading handed
259
+ * both without being told which was wanted has two answers and no way to
260
+ * choose: summing them is one number about two populations — *the portal
261
+ * gains a dimension it must not silently collapse* — and picking one is
262
+ * picking by row order.
263
+ *
264
+ * **It is the caller's, like `rows-mishandled`, and it is not that fault.**
265
+ * Nothing is wrong with the rows, nothing was handed in twice and nothing is
266
+ * unaccounted for; the window is simply of more than the reading is. The fix
267
+ * is `byAudience` and one reading per form, and the remedy says so rather
268
+ * than sending anybody looking for a bad row.
269
+ */
270
+ | "audiences-mixed";
271
+ export declare const COLLECTION_FAULTS: readonly CollectionFault[];
272
+ /** One line per fault, for a surface naming what is wrong. */
273
+ export declare const describeCollectionFault: (fault: CollectionFault) => string;
274
+ /** Whose hand a fault falls to. */
275
+ export type FaultRemedy =
276
+ /** The pages: a newer broadcaster, or one whose delegation walks the ancestry. */
277
+ "senders"
278
+ /** The deployment's own configuration: the rollup window. */
279
+ | "configuration"
280
+ /** The surface that asked: it handed in a tree and a window that do not match, or two reads. */
281
+ | "caller"
282
+ /**
283
+ * Nothing the rows can name.
284
+ *
285
+ * One fault out of seven, and it is the honest answer rather than a gap: a
286
+ * missing door row is an old sender, an expired row or a hand-built counter,
287
+ * and inventing one of the three is worse than naming none.
288
+ */
289
+ | "undetermined";
290
+ export declare const FAULT_REMEDIES: readonly FaultRemedy[];
291
+ /** Whose hand this fault falls to, which is the half of a fault a person acts on. */
292
+ export declare const remedyOf: (fault: CollectionFault) => FaultRemedy;
293
+ /** Where one revision of one page stands. */
294
+ export type HealthStanding =
295
+ /** Measured, with nothing wrong that these rows can see. */
296
+ "sound"
297
+ /** At least one fault, named on the row. */
298
+ | "faulted"
299
+ /**
300
+ * Nothing was collected about this revision at all.
301
+ *
302
+ * No counters and no page views at the door, which is a page nobody opened in
303
+ * the window rather than anything wrong. Checked before the door is, so a page
304
+ * nobody read is never reported as a page the door could not price (0250).
305
+ */
306
+ | "unmeasured"
307
+ /**
308
+ * The door counted page views of this revision and no rollup has folded any of
309
+ * them.
310
+ *
311
+ * A revision published minutes ago and a collection that has stopped look
312
+ * alike in the counts, because the lag of the tallies behind the buffer is one
313
+ * window by design (0158). Where the row attests a fold and a caller handed in
314
+ * a schedule, the two are told apart and a stalled one is `faulted` instead
315
+ * (0274); where either is missing, this names the state and claims nothing
316
+ * about which it is.
317
+ */
318
+ | "unfolded";
319
+ export declare const HEALTH_STANDINGS: readonly HealthStanding[];
320
+ /** One line per standing, for a surface saying why a page is where it is. */
321
+ export declare const describeHealthStanding: (standing: HealthStanding) => string;
322
+ /** One revision of one page, and what is wrong with what was collected about it. */
323
+ export type PageHealth = {
324
+ readonly treeId: TreeId;
325
+ readonly revision: number;
326
+ /**
327
+ * The audience this row is about, or `null` where the reading named none.
328
+ *
329
+ * Two forms of one page are two rows here and not one page counted twice
330
+ * (`readingKeyOf`), for the reason two revisions of one tree are two rows: a
331
+ * deployment serving both is running both, and a health screen that showed
332
+ * one of them would be hiding a live form of a live page.
333
+ */
334
+ readonly audienceId: AudienceId | null;
335
+ readonly standing: HealthStanding;
336
+ /**
337
+ * Every fault, in the order {@link COLLECTION_FAULTS} publishes them, which is
338
+ * the order they are worth reading in: the one that costs the denominator
339
+ * first, the three that are the deployment's, then the caller's.
340
+ *
341
+ * Empty on every standing but `faulted`.
342
+ */
343
+ readonly faults: readonly CollectionFault[];
344
+ /**
345
+ * The window's view floor, carried through from the reading unchanged.
346
+ *
347
+ * A floor and not a count (0212), which is why it is never ranked and never
348
+ * added to an arrival count here.
349
+ */
350
+ readonly views: number;
351
+ /**
352
+ * Page views counted at the door, exact, or `null` where this revision has no
353
+ * row.
354
+ *
355
+ * On a faulted page these are the readers whose measurement its faults
356
+ * affect, which is what makes one faulted page worse than another.
357
+ */
358
+ readonly arrivals: number | null;
359
+ /** The same page views as the rollups saw them, or `null` with no row. */
360
+ readonly appearances: number | null;
361
+ /** This revision's own straddle rate, or `null` where nothing has opened. */
362
+ readonly inflation: number | null;
363
+ /**
364
+ * Openings no rollup has folded yet, which is a figure and never a fault here.
365
+ *
366
+ * Zero where there is no door row, because an absent row reports no openings
367
+ * rather than none pending.
368
+ */
369
+ readonly pending: number;
370
+ /**
371
+ * When a rollup last folded a window holding page views of this revision, or
372
+ * `null` where nothing attests one — including every revision with no door
373
+ * row at all.
374
+ *
375
+ * Published whether or not a schedule was handed in, because *the last fold
376
+ * of this page was at nine this morning* is the sentence an operator reads
377
+ * before any verdict about it (0274). `null` is not *never folded*: a row
378
+ * written before the column existed says the same thing, and the first fold
379
+ * after an upgrade fills it in.
380
+ */
381
+ readonly foldedAt: string | null;
382
+ /** Counters naming nodes this revision does not contain. */
383
+ readonly orphaned: number;
384
+ /** Node counters and door rows handed in more than once, added. */
385
+ readonly doubled: number;
386
+ };
387
+ /** What a deployment is collecting, and what is wrong with it. */
388
+ export type CollectionHealth = {
389
+ /** Every revision read, by tree id and newest revision first. */
390
+ readonly pages: readonly PageHealth[];
391
+ /**
392
+ * Faulted revisions the door can price, worst first.
393
+ *
394
+ * Most arrivals, then the larger view floor, then tree id and newest revision
395
+ * first — so two pages costing the same do not reorder on a refresh. By
396
+ * headcount and never by a count of faults: one fault on a page nine thousand
397
+ * people read is worse than four on a page three did (0221).
398
+ */
399
+ readonly faulted: readonly PageHealth[];
400
+ /**
401
+ * Faulted revisions with no exact arrival count, by tree id and newest
402
+ * revision first.
403
+ *
404
+ * Out of the ranking rather than in it at a guessed height, which is the
405
+ * refusal an order of pages makes about a page the door cannot scale (0250),
406
+ * said about an order of faults.
407
+ */
408
+ readonly unpriced: readonly PageHealth[];
409
+ /** The faulted page costing the most readers, which is the one to look at first. */
410
+ readonly worst: PageHealth | null;
411
+ readonly standings: Readonly<Record<HealthStanding, number>>;
412
+ /**
413
+ * How many revisions carry each fault.
414
+ *
415
+ * A count of pages and never of readers, and it does **not** add to
416
+ * {@link standings}' `faulted`: a revision with three faults is one faulted
417
+ * page and is in three of these rows.
418
+ */
419
+ readonly faults: Readonly<Record<CollectionFault, number>>;
420
+ /**
421
+ * Page views at the door of every faulted revision the door can price, added
422
+ * — each revision once however many faults it has.
423
+ *
424
+ * The headline figure: *the measurement of eleven hundred of your readers is
425
+ * wrong in some way*. Exact and addable because a page view began on one
426
+ * revision of one tree and was counted once (0219).
427
+ */
428
+ readonly readersAffected: number;
429
+ /**
430
+ * Page views at the door across every revision read, added.
431
+ *
432
+ * The weight behind `readersAffected` — a share of readers rather than a share
433
+ * of pages is what says whether a fault is marginal. This sees the pages its
434
+ * caller read and not the deployment's.
435
+ */
436
+ readonly arrivals: number;
437
+ /**
438
+ * Openings no rollup has folded, added across the revisions read.
439
+ *
440
+ * A figure and not a verdict: most of it is the ordinary one-window lag of
441
+ * the tallies behind the buffer (0158). Whether any of it is late is
442
+ * `collection-stalled`, which needs the fold's own timestamp and a schedule
443
+ * (0274) — so this number is published the same whether one was handed in or
444
+ * not.
445
+ */
446
+ readonly pending: number;
447
+ /**
448
+ * Revisions with openings waiting and no fold timestamp to judge the wait by.
449
+ *
450
+ * The honest companion to `pending`, and the state a deployment is in for one
451
+ * run after it upgrades past the `folded_at` column: the openings are real,
452
+ * the lag may be a minute or a fortnight, and the rows do not say. A surface
453
+ * showing `pending` without this would let a reader take *no fault* for
454
+ * *nothing is late*.
455
+ *
456
+ * It counts rows rather than readers, and it is **not** a fault: nothing is
457
+ * wrong with a row that cannot answer a question nobody could ask of it
458
+ * before today.
459
+ */
460
+ readonly unattested: number;
461
+ /**
462
+ * Distinct trees across the revisions read, which is not the number of pages.
463
+ *
464
+ * Two revisions of one tree are two live versions of one page and both stand
465
+ * here, as they do in an order of pages (0250) and a census of a library
466
+ * (0257).
467
+ */
468
+ readonly trees: number;
469
+ /**
470
+ * Readings of a revision beyond the first, which were dropped.
471
+ *
472
+ * The one lie this reading can be told: a caller holding one page twice would
473
+ * have its readers counted twice in `readersAffected`, and a count that has
474
+ * been added cannot be unadded (0158).
475
+ */
476
+ readonly duplicated: number;
477
+ };
478
+ /**
479
+ * What a deployment is collecting, read off the page readings and the door rows
480
+ * it already has.
481
+ *
482
+ * Takes the readings rather than the counters, as every derived reading here
483
+ * does: the join to the tree is what makes an orphaned counter and an uncredited
484
+ * action visible at all, and deriving it twice is how two screens come to
485
+ * disagree. A caller with counters and trees reads the parts, then this.
486
+ *
487
+ * The rows are the whole window of door rows a deployment holds, not one page's
488
+ * — each revision's own row is picked out of them by the published rule (0219),
489
+ * so no caller writes the matching itself.
490
+ *
491
+ * The schedule is optional and is the only argument here that is not a row: a
492
+ * caller that states what its collection promises gets `collection-stalled`
493
+ * judged for it, and one that does not gets every other fault and `pending`
494
+ * published unjudged (0274).
495
+ */
496
+ export declare const collectionHealthOf: (readings: readonly PageReading[], rows: readonly StoredPageViews[], schedule?: CollectionSchedule) => CollectionHealth;
497
+ //# sourceMappingURL=health.d.ts.map