@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.
- package/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- package/dist/cli/templates.js +19 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +30 -3
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.js +102 -7
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +22 -0
- package/dist/runtime/index.d.ts +3 -0
- package/dist/runtime/index.js +3 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +299 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +65 -0
- package/dist/sdk/definition.js +22 -0
- package/dist/sdk/registry.d.ts +29 -2
- package/dist/sdk/registry.js +63 -1
- package/dist/signals/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -0
- package/dist/signals/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +8 -2
- package/dist/signals/broadcast.js +58 -8
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +41 -0
- package/dist/signals/collect.js +88 -7
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/counters.d.ts +46 -0
- package/dist/signals/counters.js +102 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +371 -0
- package/dist/signals/deployment-change.js +268 -0
- package/dist/signals/deployment.d.ts +265 -0
- package/dist/signals/deployment.js +152 -0
- package/dist/signals/door.d.ts +92 -0
- package/dist/signals/door.js +53 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel.d.ts +532 -0
- package/dist/signals/funnel.js +216 -0
- package/dist/signals/health.d.ts +497 -0
- package/dist/signals/health.js +361 -0
- package/dist/signals/index.d.ts +41 -0
- package/dist/signals/index.js +41 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/journal.d.ts +11 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -0
- package/dist/signals/library-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +636 -0
- package/dist/signals/library-reach-change.js +534 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +568 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +105 -14
- package/dist/signals/migrate.d.ts +17 -2
- package/dist/signals/migrate.js +122 -5
- package/dist/signals/notice.d.ts +334 -0
- package/dist/signals/notice.js +228 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/parts.d.ts +344 -0
- package/dist/signals/parts.js +273 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +390 -87
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +141 -0
- package/dist/signals/retention.js +58 -0
- package/dist/signals/rollup.d.ts +67 -3
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +432 -1
- package/dist/signals/schema.js +157 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +848 -0
- package/dist/signals/silences.js +753 -0
- package/dist/signals/tally.d.ts +140 -11
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -0
- package/dist/store/index.d.ts +19 -0
- package/dist/store/index.js +19 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +80 -0
- package/dist/store/migrate.js +259 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +16 -1
- package/dist/store/postgres.js +59 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +450 -2
- package/dist/store/schema.js +141 -5
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +72 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +23 -0
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +172 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/contracts.d.ts +12 -7
- package/dist/testing/contracts.js +12 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +140 -2
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- package/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +98 -19
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
import { everyMemberOf } from "../closed-set.js";
|
|
2
|
+
import { countWords } from "./words.js";
|
|
3
|
+
/**
|
|
4
|
+
* Whether a part was read or scrolled past.
|
|
5
|
+
*
|
|
6
|
+
* [`parts.ts`](parts.ts) answers *which parts came into view*, and it has
|
|
7
|
+
* always been careful to say only that: `read` there means **a row says this
|
|
8
|
+
* part was on a reader's screen**. A band a reader scrolled through at speed is
|
|
9
|
+
* `read` by that definition and was not read by any other, and a page of them
|
|
10
|
+
* reports as a page that was read from top to bottom. That is the
|
|
11
|
+
* plausible-false-number failure this subsystem keeps finding in new places —
|
|
12
|
+
* the figure is the right shape, it is on the screen, and nobody can tell it is
|
|
13
|
+
* wrong.
|
|
14
|
+
*
|
|
15
|
+
* The missing half was already in the rows. A tally carries `dwellMs` beside
|
|
16
|
+
* `reached`, and since [0223](../../decisions/0223-a-prop-is-copy-when-a-reader-could-quote-it.md)
|
|
17
|
+
* the tree carries the words a part says. **Time on screen against the time its
|
|
18
|
+
* words take to read** is the question, and both sides of it are already held:
|
|
19
|
+
* nothing is added to a payload, a browser, a column, a store or the
|
|
20
|
+
* vocabulary. It is the fifth thing taken out of the server-side join of
|
|
21
|
+
* [0212](../../decisions/0212-what-a-reader-signal-means-is-joined-to-the-tree-when-it-is-read.md)
|
|
22
|
+
* rather than collected.
|
|
23
|
+
*
|
|
24
|
+
* ## A verdict in one direction only
|
|
25
|
+
*
|
|
26
|
+
* Three things bias the comparison, and all three bias it the same way.
|
|
27
|
+
*
|
|
28
|
+
* - **Dwell is time on screen, not time reading.** `READABLE_VISIBLE_FRACTION`
|
|
29
|
+
* says half of an element showing is enough ([0218](../../decisions/0218-what-a-counter-means-is-published-and-the-browser-pays-for-the-number-and-not-its-name.md)),
|
|
30
|
+
* so a part sits accumulating dwell while a reader reads its neighbour, and
|
|
31
|
+
* an ancestor accumulates dwell for the whole time any of its children was up.
|
|
32
|
+
* - **A word count can be a floor.** A type that declares no `copy` has words
|
|
33
|
+
* nothing can see (0122), and a declared prop holding something other than a
|
|
34
|
+
* string is a word owed and not given. Either way the part says *at least*
|
|
35
|
+
* this much.
|
|
36
|
+
* - **The reader count is generous.** `reached` is a distinct view count summed
|
|
37
|
+
* across rollup windows (0147), so a reader who straddled a boundary is two,
|
|
38
|
+
* and the mean time per reader is short by that much. This is the one of the
|
|
39
|
+
* three that is measured rather than argued, and {@link PaceOptions.inflation}
|
|
40
|
+
* is where a deployment hands the measurement in (0219).
|
|
41
|
+
*
|
|
42
|
+
* So the time a reader is credited with is generous, the words they had to get
|
|
43
|
+
* through are a floor, and **`skimmed` is the only verdict that survives all
|
|
44
|
+
* three**: it says the time on screen was short *even after* every doubt has
|
|
45
|
+
* been resolved in the page's favour. `paced` and `lingered` are the weaker
|
|
46
|
+
* claims, and where the words are a floor they are not made at all — the part
|
|
47
|
+
* goes back to `unknown`, with {@link PaceSilence} saying why.
|
|
48
|
+
*
|
|
49
|
+
* That asymmetry is the whole design and it is deliberate. *Readers are not
|
|
50
|
+
* reading this* is worth being sure of. *Readers read this* is a thing nobody
|
|
51
|
+
* acts on.
|
|
52
|
+
*
|
|
53
|
+
* ## Nesting, and the sums that are therefore missing
|
|
54
|
+
*
|
|
55
|
+
* A part is judged against its own subtree's words, because the words on screen
|
|
56
|
+
* while a band was up are the band's and its children's. So figures nest: a
|
|
57
|
+
* band and the paragraph inside it are both here, and the paragraph's words are
|
|
58
|
+
* in the band's count. Nothing on a page total adds them, and there is no
|
|
59
|
+
* page-wide word figure at all — one reader who scrolled past a band scrolled
|
|
60
|
+
* past everything in it, and a sum would charge them for it once per level.
|
|
61
|
+
*
|
|
62
|
+
* Pure, linear in the parts, and reaches no store, clock or DOM — it adds
|
|
63
|
+
* nothing to the broadcaster's import graph.
|
|
64
|
+
*/
|
|
65
|
+
/**
|
|
66
|
+
* The rate a page's words are costed at, in words per minute.
|
|
67
|
+
*
|
|
68
|
+
* Published for the reason the readable fractions are (0218): a number that
|
|
69
|
+
* decides what a counter **means** should be quotable by the page explaining
|
|
70
|
+
* it, rather than retyped beside the noun it qualifies. 240 is the middle of
|
|
71
|
+
* the range usually reported for adult silent reading of ordinary prose, and it
|
|
72
|
+
* is a costing rate rather than a claim about any reader — the verdicts are
|
|
73
|
+
* built to survive being wrong about it by a wide margin in either direction.
|
|
74
|
+
*
|
|
75
|
+
* **Unlike the readable fractions, this one may be overridden**, and the
|
|
76
|
+
* difference is which side of the wire it lives on. Those two are applied in a
|
|
77
|
+
* browser and are baked into every counter already written. This is applied
|
|
78
|
+
* when the rows are read (0212), so a deployment that changes it reinterprets
|
|
79
|
+
* its whole history and invalidates nothing. What it may change is the rate,
|
|
80
|
+
* which is a fact about its own text and its own language that the framework
|
|
81
|
+
* cannot know; the thresholds below are the framework's statement of how much
|
|
82
|
+
* margin a claim needs, and are not a dial.
|
|
83
|
+
*/
|
|
84
|
+
export const READING_WORDS_PER_MINUTE = 240;
|
|
85
|
+
/**
|
|
86
|
+
* Below this much of the time its words take, a part was not read.
|
|
87
|
+
*
|
|
88
|
+
* Half. Low enough that the verdict holds through all three biases above, which
|
|
89
|
+
* is what makes it the claim worth putting on a screen.
|
|
90
|
+
*/
|
|
91
|
+
export const SKIMMED_BELOW = 0.5;
|
|
92
|
+
/**
|
|
93
|
+
* Above this much, readers stayed longer than the words account for.
|
|
94
|
+
*
|
|
95
|
+
* A weak signal by construction, because dwell counts a part that was merely up
|
|
96
|
+
* while something else was being read. It is a question — *is this where people
|
|
97
|
+
* get stuck, or is it just the tall thing at the bottom of the page* — and not
|
|
98
|
+
* an answer.
|
|
99
|
+
*/
|
|
100
|
+
export const LINGERED_ABOVE = 3;
|
|
101
|
+
export const PACE_STANDINGS = everyMemberOf()([
|
|
102
|
+
"skimmed",
|
|
103
|
+
"paced",
|
|
104
|
+
"lingered",
|
|
105
|
+
"unknown",
|
|
106
|
+
]);
|
|
107
|
+
export const PACE_SILENCES = everyMemberOf()([
|
|
108
|
+
"unreached",
|
|
109
|
+
"unreadable",
|
|
110
|
+
"wordless",
|
|
111
|
+
]);
|
|
112
|
+
/** One line per standing, for a surface putting the reading in front of a person. */
|
|
113
|
+
export const describePaceStanding = (standing) => {
|
|
114
|
+
switch (standing) {
|
|
115
|
+
case "skimmed":
|
|
116
|
+
return "readers had too little time on it to have read its words";
|
|
117
|
+
case "paced":
|
|
118
|
+
return "readers had time enough for its words";
|
|
119
|
+
case "lingered":
|
|
120
|
+
return "readers stayed well past what its words account for";
|
|
121
|
+
case "unknown":
|
|
122
|
+
return "nothing could be compared";
|
|
123
|
+
}
|
|
124
|
+
};
|
|
125
|
+
/** One line per silence, for the same surface. */
|
|
126
|
+
export const describePaceSilence = (silence) => {
|
|
127
|
+
switch (silence) {
|
|
128
|
+
case "unreached":
|
|
129
|
+
return "no view reported it coming into view";
|
|
130
|
+
case "unreadable":
|
|
131
|
+
return "some of its words could not be read, so only a skim could be claimed";
|
|
132
|
+
case "wordless":
|
|
133
|
+
return "it says nothing that takes time to read";
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
const NO_STANDINGS = Object.freeze({
|
|
137
|
+
skimmed: 0,
|
|
138
|
+
paced: 0,
|
|
139
|
+
lingered: 0,
|
|
140
|
+
unknown: 0,
|
|
141
|
+
});
|
|
142
|
+
const NO_SILENCES = Object.freeze({
|
|
143
|
+
unreached: 0,
|
|
144
|
+
unreadable: 0,
|
|
145
|
+
wordless: 0,
|
|
146
|
+
});
|
|
147
|
+
const MS_PER_MINUTE = 60_000;
|
|
148
|
+
/** What a part contributes on its own: its words, and whether any of them got away. */
|
|
149
|
+
const ownWords = (part) => ({
|
|
150
|
+
words: countWords(part.copy.words),
|
|
151
|
+
floored: part.copy.unread.length > 0 || part.copy.unspoken.length > 0,
|
|
152
|
+
});
|
|
153
|
+
/** The totals of a part that is not there to have any, which no reading produces. */
|
|
154
|
+
const NOTHING_SAID = Object.freeze({ words: 0, floored: false });
|
|
155
|
+
/**
|
|
156
|
+
* Each part's subtree totals, in one pass over the reading.
|
|
157
|
+
*
|
|
158
|
+
* The parts are pre-order with depths, so a part's subtree is the run of
|
|
159
|
+
* following parts deeper than it — which a stack closes in constant amortised
|
|
160
|
+
* time per part. **Depth rather than `parentId`**, because a slot node is not a
|
|
161
|
+
* part and can hold element children: walking the parent chain would strand a
|
|
162
|
+
* whole band's words on a node this reading has never heard of, and the stack
|
|
163
|
+
* cannot, since it only ever asks whether the next part is deeper.
|
|
164
|
+
*/
|
|
165
|
+
const subtreesOf = (parts) => {
|
|
166
|
+
const totals = [];
|
|
167
|
+
const open = [];
|
|
168
|
+
const close = () => {
|
|
169
|
+
const frame = open.pop();
|
|
170
|
+
if (frame === undefined)
|
|
171
|
+
return;
|
|
172
|
+
totals[frame.index] = { words: frame.words, floored: frame.floored };
|
|
173
|
+
const parent = open[open.length - 1];
|
|
174
|
+
if (parent === undefined)
|
|
175
|
+
return;
|
|
176
|
+
parent.words += frame.words;
|
|
177
|
+
parent.floored = parent.floored || frame.floored;
|
|
178
|
+
};
|
|
179
|
+
parts.forEach((part, index) => {
|
|
180
|
+
while ((open[open.length - 1]?.depth ?? -1) >= part.depth)
|
|
181
|
+
close();
|
|
182
|
+
const own = ownWords(part);
|
|
183
|
+
open.push({ index, depth: part.depth, words: own.words, floored: own.floored });
|
|
184
|
+
});
|
|
185
|
+
while (open.length > 0)
|
|
186
|
+
close();
|
|
187
|
+
return totals;
|
|
188
|
+
};
|
|
189
|
+
/**
|
|
190
|
+
* The verdict, which is the asymmetry of the module documentation written once.
|
|
191
|
+
*
|
|
192
|
+
* `skimmed` is reached before the floor is consulted, because words nobody
|
|
193
|
+
* counted can only make a part more skimmed than it already reads. Everything
|
|
194
|
+
* after that point is a claim the floor could overturn.
|
|
195
|
+
*
|
|
196
|
+
* **Published** because a comparison of two windows asks it of a pace neither
|
|
197
|
+
* window reported — the pace a part would have had if the change had not
|
|
198
|
+
* touched its words ([`pace-change.ts`](pace-change.ts)) — and a second
|
|
199
|
+
* spelling of this rule is the thing this subsystem has already been bitten by
|
|
200
|
+
* twice: two counter keys that agreed until they did not, and two word counts
|
|
201
|
+
* that agreed until one of them learned about slots.
|
|
202
|
+
*/
|
|
203
|
+
export const paceStandingOf = (pace, floored) => {
|
|
204
|
+
if (pace === null)
|
|
205
|
+
return "unknown";
|
|
206
|
+
if (pace < SKIMMED_BELOW)
|
|
207
|
+
return "skimmed";
|
|
208
|
+
if (floored)
|
|
209
|
+
return "unknown";
|
|
210
|
+
return pace > LINGERED_ABOVE ? "lingered" : "paced";
|
|
211
|
+
};
|
|
212
|
+
const silenceOf = (readers, wordsWithin, floored) => {
|
|
213
|
+
if (readers === 0)
|
|
214
|
+
return "unreached";
|
|
215
|
+
return wordsWithin === 0 && !floored ? "wordless" : "unreadable";
|
|
216
|
+
};
|
|
217
|
+
/** A positive, finite option, or the fallback. Everything else is refused. */
|
|
218
|
+
const positive = (value, fallback) => value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
|
|
219
|
+
const pacedPart = (part, subtree, inflation, msPerWord) => {
|
|
220
|
+
const own = ownWords(part);
|
|
221
|
+
const readers = part.counters?.reached ?? 0;
|
|
222
|
+
const dwellMs = part.counters?.dwellMs ?? 0;
|
|
223
|
+
const needMs = subtree.words * msPerWord;
|
|
224
|
+
/**
|
|
225
|
+
* A page view that straddled a rollup window is one reader counted twice
|
|
226
|
+
* carrying one reader's dwell (0147), so the mean is short by the same
|
|
227
|
+
* proportion the inflation names.
|
|
228
|
+
* Multiplying the time is the same correction as dividing the readers and
|
|
229
|
+
* keeps `readers` the integer the rows actually hold.
|
|
230
|
+
*/
|
|
231
|
+
const spentMs = readers === 0 ? null : (dwellMs * (1 + inflation)) / readers;
|
|
232
|
+
const pace = spentMs === null || needMs === 0 ? null : spentMs / needMs;
|
|
233
|
+
const standing = paceStandingOf(pace, subtree.floored);
|
|
234
|
+
return {
|
|
235
|
+
nodeId: part.nodeId,
|
|
236
|
+
type: part.type,
|
|
237
|
+
role: part.role,
|
|
238
|
+
depth: part.depth,
|
|
239
|
+
parentId: part.parentId,
|
|
240
|
+
readers,
|
|
241
|
+
words: own.words,
|
|
242
|
+
wordsWithin: subtree.words,
|
|
243
|
+
floored: subtree.floored,
|
|
244
|
+
dwellMs,
|
|
245
|
+
spentMs,
|
|
246
|
+
needMs,
|
|
247
|
+
pace,
|
|
248
|
+
standing,
|
|
249
|
+
silence: standing === "unknown" ? silenceOf(readers, subtree.words, subtree.floored) : null,
|
|
250
|
+
wordsPassed: readers * subtree.words,
|
|
251
|
+
};
|
|
252
|
+
};
|
|
253
|
+
/**
|
|
254
|
+
* The more skimmed of two, which is the ranking rule spelled once.
|
|
255
|
+
*
|
|
256
|
+
* `>` rather than `>=` is what makes *first in reading order* hold without a
|
|
257
|
+
* second comparison: an equal candidate never displaces the one already
|
|
258
|
+
* standing, and the parts arrive in reading order.
|
|
259
|
+
*/
|
|
260
|
+
const worseOf = (standing, next) => standing === null || next.wordsPassed > standing.wordsPassed ? next : standing;
|
|
261
|
+
/**
|
|
262
|
+
* Whether readers had time to read what each part of a page says.
|
|
263
|
+
*
|
|
264
|
+
* Handed the output of `pageReadingOf`, because the words, the counters and the
|
|
265
|
+
* reading order are all already joined there and deriving them a second time is
|
|
266
|
+
* how two screens come to disagree.
|
|
267
|
+
*/
|
|
268
|
+
export const readingPaceOf = (reading, options = {}) => {
|
|
269
|
+
const inflation = positive(options.inflation, 0);
|
|
270
|
+
const wordsPerMinute = positive(options.wordsPerMinute, READING_WORDS_PER_MINUTE);
|
|
271
|
+
const msPerWord = MS_PER_MINUTE / wordsPerMinute;
|
|
272
|
+
const subtrees = subtreesOf(reading.parts);
|
|
273
|
+
const parts = reading.parts.map((part, index) => pacedPart(part, subtrees[index] ?? NOTHING_SAID, inflation, msPerWord));
|
|
274
|
+
const standings = parts.reduce((counted, part) => ({ ...counted, [part.standing]: counted[part.standing] + 1 }), { ...NO_STANDINGS });
|
|
275
|
+
const silences = parts.reduce((counted, part) => part.silence === null ? counted : { ...counted, [part.silence]: counted[part.silence] + 1 }, { ...NO_SILENCES });
|
|
276
|
+
const whole = parts.find((part) => part.depth === 0) ?? null;
|
|
277
|
+
const mostSkimmed = parts.reduce((standing, next) => next.standing === "skimmed" && next !== whole ? worseOf(standing, next) : standing, null);
|
|
278
|
+
return {
|
|
279
|
+
treeId: reading.treeId,
|
|
280
|
+
revision: reading.revision,
|
|
281
|
+
views: reading.views,
|
|
282
|
+
parts,
|
|
283
|
+
standings,
|
|
284
|
+
silences,
|
|
285
|
+
whole,
|
|
286
|
+
mostSkimmed,
|
|
287
|
+
inflation,
|
|
288
|
+
wordsPerMinute,
|
|
289
|
+
};
|
|
290
|
+
};
|
|
291
|
+
//# sourceMappingURL=pace.js.map
|
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
2
|
+
import type { TreeId } from "../ids.js";
|
|
3
|
+
import type { ReaderSignalBatch } from "./signal.js";
|
|
4
|
+
/**
|
|
5
|
+
* How many page views there were — the number every rate on a screen is taken
|
|
6
|
+
* of, and the one number this subsystem could not state.
|
|
7
|
+
*
|
|
8
|
+
* Everything else here counts what happened *inside* a page view: time on a
|
|
9
|
+
* band, presses under a region, forms let go. The denominator was the summed
|
|
10
|
+
* `views` on a tally, which is a distinct count added across rollup windows and
|
|
11
|
+
* therefore generous by every page view that straddled a boundary
|
|
12
|
+
* ([0147](../../decisions/0147-a-rollup-is-added-to-what-is-stored-and-a-distinct-view-count-is-therefore-approximate.md)).
|
|
13
|
+
* 0147 bounds that error by arithmetic nobody can evaluate from the rows —
|
|
14
|
+
* *views per window × page-view duration ÷ window length* — so a portal showing
|
|
15
|
+
* a rate could say it was slightly high and never how high.
|
|
16
|
+
*
|
|
17
|
+
* **Two numbers for the same page views, counted from opposite ends.** A batch
|
|
18
|
+
* says whether it opened its page view (0214), which is a fact only a sender
|
|
19
|
+
* has, so `opened` is counted at the door, once, and never recounted. A rollup
|
|
20
|
+
* counts the same page views once per window they appeared in, which is
|
|
21
|
+
* `appearances`. For an honest sender the two differ by exactly the straddles,
|
|
22
|
+
* so **the over-count stops being a bound and becomes a measurement** — a
|
|
23
|
+
* subtraction of two stored numbers, per revision, for as long as the counters
|
|
24
|
+
* live.
|
|
25
|
+
*
|
|
26
|
+
* It costs no byte on the wire and no byte in a browser: the marker it reads
|
|
27
|
+
* already ships for the region counter, and this is the second thing derived
|
|
28
|
+
* from it rather than a second thing sent.
|
|
29
|
+
*
|
|
30
|
+
* **One of the two numbers now says when it was written, and the other
|
|
31
|
+
* deliberately does not.** `appearances` carries `foldedAt`, stamped by the
|
|
32
|
+
* rollup and by nothing else, because the subtraction above has a second sign:
|
|
33
|
+
* `opened − appearances` is the openings no fold has reached, which is the
|
|
34
|
+
* buffer as a number *and* what a collection that has stopped looks like. The
|
|
35
|
+
* row's `updatedAt` cannot tell those apart — the door writes it on every
|
|
36
|
+
* delivery — so the fold's own timestamp is the one thing that can, and a
|
|
37
|
+
* reading judges a lag against the schedule its deployment hands in
|
|
38
|
+
* ([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)).
|
|
39
|
+
*
|
|
40
|
+
* **There is no floor here, and that is not an oversight.** A region bucket is
|
|
41
|
+
* floored because a country with four views in it is a person
|
|
42
|
+
* ([0214](../../decisions/0214-where-readers-are-is-a-floored-bucket-counted-at-the-door-and-a-page-view-says-when-it-began.md));
|
|
43
|
+
* a count of page views of a revision names nowhere and nobody, so there is
|
|
44
|
+
* nothing in it to withhold. Four page views of revision 3 is four page views
|
|
45
|
+
* of revision 3.
|
|
46
|
+
*
|
|
47
|
+
* **A page served in two forms has two doors, and a deployment-wide reading
|
|
48
|
+
* adds them.** The store keeps one row per revision per audience (0284), so a
|
|
49
|
+
* revision served to two audiences (0263) is counted twice over — and a reading
|
|
50
|
+
* that named no audience used to take whichever row came first and report the
|
|
51
|
+
* other as a row handed in twice, which published one form's arrivals and
|
|
52
|
+
* called the rest a duplicate. They add because **arrivals are people**: a
|
|
53
|
+
* reader who arrived arrived once whichever form they were served, so the sum
|
|
54
|
+
* is one deployment's arrivals and the census beside it says what it was a sum
|
|
55
|
+
* over (0297, 0299). It is the opposite of a page reading, where adding two
|
|
56
|
+
* forms' node counters would be one number about two pages (0290) — and the
|
|
57
|
+
* asymmetry is not a special case for arrivals but the plainest instance of the
|
|
58
|
+
* rule that what may be added is whatever was counted once.
|
|
59
|
+
*/
|
|
60
|
+
/**
|
|
61
|
+
* One revision's worth of page views, as whichever side counted them.
|
|
62
|
+
*
|
|
63
|
+
* The same shape for both writers, because they are counting the same thing by
|
|
64
|
+
* two routes and a reading subtracts them. What the number *means* is the
|
|
65
|
+
* method it was handed to, which is where the two senses are named.
|
|
66
|
+
*/
|
|
67
|
+
export type RevisionViews = {
|
|
68
|
+
readonly treeId: TreeId;
|
|
69
|
+
readonly revision: number;
|
|
70
|
+
readonly views: number;
|
|
71
|
+
};
|
|
72
|
+
/** Page views of one revision of one tree, counted from both ends. */
|
|
73
|
+
export type ReaderPageViews = {
|
|
74
|
+
readonly treeId: TreeId;
|
|
75
|
+
readonly revision: number;
|
|
76
|
+
/**
|
|
77
|
+
* Page views that *began* on this revision.
|
|
78
|
+
*
|
|
79
|
+
* Exact, in the sense that matters: counted once, at the instant a page view
|
|
80
|
+
* opened, never recounted, and therefore addable across windows, revisions,
|
|
81
|
+
* trees and months. The two things it is not exact against are worth knowing
|
|
82
|
+
* — a sender that retries an opening delivery after the first one was kept
|
|
83
|
+
* counts twice, and a count cannot be uncounted (0158); and a sender is what
|
|
84
|
+
* says it opened at all, so a page that lies inflates this the way it could
|
|
85
|
+
* already inflate a region bucket. The rate limiter is what bounds both.
|
|
86
|
+
*/
|
|
87
|
+
readonly opened: number;
|
|
88
|
+
/**
|
|
89
|
+
* The same page views as the rollups saw them: once per window each appeared
|
|
90
|
+
* in.
|
|
91
|
+
*
|
|
92
|
+
* Which is why it is kept at all. On its own it is the count a rollup can
|
|
93
|
+
* only approximate (0147); beside `opened` it is the measurement of that
|
|
94
|
+
* approximation, because the only way the two can differ for an honest sender
|
|
95
|
+
* is a page view whose batches landed in more than one window.
|
|
96
|
+
*/
|
|
97
|
+
readonly appearances: number;
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* A page-view row as the store keeps it, which is the pair, when it last moved,
|
|
101
|
+
* and when the fold last touched it.
|
|
102
|
+
*/
|
|
103
|
+
export type StoredPageViews = ReaderPageViews & {
|
|
104
|
+
/** The audience these page views were served under. See `StoredTally.audienceId` (0284). */
|
|
105
|
+
readonly audienceId: AudienceId;
|
|
106
|
+
/**
|
|
107
|
+
* When either writer last moved this row.
|
|
108
|
+
*
|
|
109
|
+
* Written by the door on every delivery that opened a page view *and* by
|
|
110
|
+
* every rollup that folded one, which is what makes it useless for telling a
|
|
111
|
+
* stalled collection from a quiet one: a busy page whose rollup has stopped
|
|
112
|
+
* keeps a fresh timestamp while its appearances never move again.
|
|
113
|
+
*/
|
|
114
|
+
readonly updatedAt: string;
|
|
115
|
+
/**
|
|
116
|
+
* When a rollup last folded a window holding page views of this revision, or
|
|
117
|
+
* absent where nothing attests a fold.
|
|
118
|
+
*
|
|
119
|
+
* **Absent is not *never folded*.** It is *nothing here can say*: a row
|
|
120
|
+
* written before the column existed, a store a caller built by hand, a
|
|
121
|
+
* fixture. The two cases are one state, no reading claims anything from it,
|
|
122
|
+
* and the first fold after an upgrade fills it in (0274).
|
|
123
|
+
*
|
|
124
|
+
* Where it *is* there, it is the one timestamp in this subsystem written by a
|
|
125
|
+
* single writer, and therefore the only thing that can say an opening has
|
|
126
|
+
* been pending longer than it should be.
|
|
127
|
+
*/
|
|
128
|
+
readonly foldedAt?: string;
|
|
129
|
+
};
|
|
130
|
+
/**
|
|
131
|
+
* The page views a delivery opened, per revision, deduplicated by view key.
|
|
132
|
+
*
|
|
133
|
+
* The dedup inside the delivery is load-bearing rather than defensive: a sender
|
|
134
|
+
* draining a queue after an outage posts what it has, which may include an
|
|
135
|
+
* opening batch it already sent and could not confirm, and a page view counted
|
|
136
|
+
* twice cannot be uncounted
|
|
137
|
+
* ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
|
|
138
|
+
* Keys are compared rather than batches, so one opening delivered twice is one
|
|
139
|
+
* page view and two page views opened in one delivery are two.
|
|
140
|
+
*
|
|
141
|
+
* A batch that opened nothing adds nothing, and a sender that never says adds
|
|
142
|
+
* nothing at all — a batch synthesised on a server or replayed from a fixture
|
|
143
|
+
* is not an arrival, exactly as it is not a view (0146). The parser has already
|
|
144
|
+
* refused a batch that claims an opening and names no page view, so a key is
|
|
145
|
+
* always there to compare when the claim is.
|
|
146
|
+
*
|
|
147
|
+
* Pure, and shared: the region counter stamps a country onto these rows rather
|
|
148
|
+
* than walking the delivery itself, which is what keeps the two counters from
|
|
149
|
+
* disagreeing about how many readers arrived.
|
|
150
|
+
*/
|
|
151
|
+
export declare const openingsOf: (batches: readonly ReaderSignalBatch[]) => readonly RevisionViews[];
|
|
152
|
+
/**
|
|
153
|
+
* One revision, as a reading reports it — the stored row, and what subtracting
|
|
154
|
+
* its two numbers says.
|
|
155
|
+
*
|
|
156
|
+
* `updatedAt` travels with it because a page-view figure that has not moved in a
|
|
157
|
+
* day is a fact about the deployment rather than about its readers, and a screen
|
|
158
|
+
* showing the number should be able to say when it last did.
|
|
159
|
+
*/
|
|
160
|
+
export type RevisionPageViews = ReaderPageViews & {
|
|
161
|
+
/**
|
|
162
|
+
* The audience this reading is of, or `null` where it is of every form the
|
|
163
|
+
* window held.
|
|
164
|
+
*
|
|
165
|
+
* The same three-valued field `RegionReading.audienceId` is, and the
|
|
166
|
+
* same rule: it is what the *asking* named and never what the rows turned out
|
|
167
|
+
* to say. One row naming one form is not a reading of one form — a window may
|
|
168
|
+
* simply hold one today — so a single-membered census does not fill this in
|
|
169
|
+
* (0297, 0299).
|
|
170
|
+
*/
|
|
171
|
+
readonly audienceId: AudienceId | null;
|
|
172
|
+
/**
|
|
173
|
+
* The audiences whose rows were added into this reading, deduplicated and in
|
|
174
|
+
* a stable order.
|
|
175
|
+
*
|
|
176
|
+
* `[]` where the rows named none, one name where this is one form's door, and
|
|
177
|
+
* **more than one where it is a sum over forms, which is a measurement rather
|
|
178
|
+
* than a fault**: a page served in two forms (0263) has two door rows (0284),
|
|
179
|
+
* and a reader who arrived arrived once whichever form they were served, so
|
|
180
|
+
* the sum is one deployment's arrivals (0297, 0299). Compare a page reading,
|
|
181
|
+
* where adding two forms' node counters is one number about two pages and
|
|
182
|
+
* `PageHealth` calls it `audiences-mixed` (0290).
|
|
183
|
+
*/
|
|
184
|
+
readonly audiences: readonly AudienceId[];
|
|
185
|
+
/**
|
|
186
|
+
* When either writer last moved a row behind this reading — the newest of
|
|
187
|
+
* them where it is a sum, because the question is when the number last
|
|
188
|
+
* changed and the busiest form is what last changed it.
|
|
189
|
+
*
|
|
190
|
+
* See {@link StoredPageViews.updatedAt} for why it cannot tell a stalled
|
|
191
|
+
* collection from a quiet one.
|
|
192
|
+
*/
|
|
193
|
+
readonly updatedAt: string;
|
|
194
|
+
/**
|
|
195
|
+
* The fold this reading is waiting on: the oldest fold attested by a row that
|
|
196
|
+
* still has openings pending, or the oldest attested of them all where none
|
|
197
|
+
* has, and absent where nothing attests one.
|
|
198
|
+
*
|
|
199
|
+
* For one form's door that is simply {@link StoredPageViews.foldedAt}. For a
|
|
200
|
+
* sum over forms it is the only choice that keeps a fault from hiding behind
|
|
201
|
+
* a busier form — a fold that ran a minute ago on one form cannot vouch for a
|
|
202
|
+
* form whose openings have been waiting a day — and it is *the oldest of the
|
|
203
|
+
* rows still waiting* rather than the oldest of all of them so that a quiet
|
|
204
|
+
* form with nothing pending cannot invent a stall. A summed door is therefore
|
|
205
|
+
* stalled exactly when one of its forms is (0299).
|
|
206
|
+
*/
|
|
207
|
+
readonly foldedAt?: string;
|
|
208
|
+
/**
|
|
209
|
+
* Appearances in excess of openings — the over-count in every distinct view
|
|
210
|
+
* count stored against this revision, measured rather than bounded.
|
|
211
|
+
*
|
|
212
|
+
* Never negative: a reading taken between a door write and the next rollup
|
|
213
|
+
* sees openings the counters have not met yet, and that is `pending` rather
|
|
214
|
+
* than a negative drift.
|
|
215
|
+
*/
|
|
216
|
+
readonly drift: number;
|
|
217
|
+
/**
|
|
218
|
+
* Page views that began and whose batches no rollup has folded yet — the
|
|
219
|
+
* buffer, as a number.
|
|
220
|
+
*
|
|
221
|
+
* It is the other sign of the same subtraction, so **one form's door never
|
|
222
|
+
* has both** — and a door summed over two forms can, because the two are
|
|
223
|
+
* added per row rather than taken from the two sums (0299): one form
|
|
224
|
+
* mid-collection and one form with straddles is a revision with six of each,
|
|
225
|
+
* and netting them would report it as exactly measured, which neither form
|
|
226
|
+
* is. A reading that showed neither would make a deployment whose collection
|
|
227
|
+
* has stopped look like a deployment whose readers had left.
|
|
228
|
+
*/
|
|
229
|
+
readonly pending: number;
|
|
230
|
+
/**
|
|
231
|
+
* `drift ÷ opened`: how generous the distinct counts against this revision
|
|
232
|
+
* are, as a fraction. `null` when nothing has opened, because the question
|
|
233
|
+
* has no answer rather than the answer nought.
|
|
234
|
+
*/
|
|
235
|
+
readonly inflation: number | null;
|
|
236
|
+
};
|
|
237
|
+
export type PageViewReading = {
|
|
238
|
+
/** Page views that began, across every row read. Exact, and addable. */
|
|
239
|
+
readonly opened: number;
|
|
240
|
+
readonly appearances: number;
|
|
241
|
+
readonly drift: number;
|
|
242
|
+
readonly pending: number;
|
|
243
|
+
readonly inflation: number | null;
|
|
244
|
+
/** Newest revision first, trees in id order, so a screen does not reorder on a refresh. */
|
|
245
|
+
readonly revisions: readonly RevisionPageViews[];
|
|
246
|
+
};
|
|
247
|
+
/**
|
|
248
|
+
* Rows from the store, read as something a screen may show.
|
|
249
|
+
*
|
|
250
|
+
* **Totalled from the rows and never from the totals.** `drift` on the whole
|
|
251
|
+
* reading is the sum of each revision's drift, not the difference of the two
|
|
252
|
+
* sums: a revision mid-collection has openings the rollups have not reached,
|
|
253
|
+
* and subtracting in the aggregate would let that cancel another revision's
|
|
254
|
+
* straddles and report a page as more exact than any part of it is.
|
|
255
|
+
*
|
|
256
|
+
* Unlike a region reading this withholds nothing, groups nothing, and hides
|
|
257
|
+
* nothing. Every row is already an aggregate about a revision of a tree.
|
|
258
|
+
*/
|
|
259
|
+
export declare const pageViewReadingOf: (rows: readonly StoredPageViews[]) => PageViewReading;
|
|
260
|
+
/**
|
|
261
|
+
* The page-view row a reading of one revision should be divided by, picked out
|
|
262
|
+
* of a window of rows.
|
|
263
|
+
*
|
|
264
|
+
* **This exists because the pairing is the part that can be got wrong, and it
|
|
265
|
+
* fails quietly.** The number a correction wants belongs to *one revision of
|
|
266
|
+
* one page*; the obvious thing to reach for is the aggregate
|
|
267
|
+
* {@link PageViewReading.inflation} published beside it, and handing a busy
|
|
268
|
+
* page's straddle rate to a quiet one is an invented correction with three
|
|
269
|
+
* decimal places on it. Nothing would fail — the figures downstream would
|
|
270
|
+
* simply be a little wrong, in whichever direction their own safety argument
|
|
271
|
+
* needs them right. So the rule lives once, here, beside the counter it is a
|
|
272
|
+
* rule about, rather than four lines in every consumer.
|
|
273
|
+
*
|
|
274
|
+
* **It filters rather than trusts its caller, and says what it dropped.** A
|
|
275
|
+
* caller who handed in a whole store's rows and one who handed in the wrong
|
|
276
|
+
* revision's look identical from the inside, so both are counted.
|
|
277
|
+
*/
|
|
278
|
+
export type PageViewsFor = {
|
|
279
|
+
/**
|
|
280
|
+
* This revision's door, read through {@link pageViewReadingOf}, or `null`
|
|
281
|
+
* where this revision has none.
|
|
282
|
+
*
|
|
283
|
+
* Read through the reading rather than subtracted again, because one
|
|
284
|
+
* definition of drift, pending and inflation is the point: a second would be
|
|
285
|
+
* a second place for them to disagree with the counter they describe.
|
|
286
|
+
*
|
|
287
|
+
* **Where the asking names no audience this is the sum of every form's
|
|
288
|
+
* door**, and it was once whichever form came first in the caller's array
|
|
289
|
+
* (0299). A page served in two forms has two door rows (0263, 0284), so a
|
|
290
|
+
* deployment-wide asking was answered with one form's openings and the other
|
|
291
|
+
* form's reported as a row handed in twice — the same quiet undercount found
|
|
292
|
+
* in the reading beside it (0297). Arrivals add because arrivals are people:
|
|
293
|
+
* a reader who arrived arrived once whichever form they were served.
|
|
294
|
+
* {@link RevisionPageViews.audiences} is what the sum was over.
|
|
295
|
+
*/
|
|
296
|
+
readonly measured: RevisionPageViews | null;
|
|
297
|
+
/**
|
|
298
|
+
* Rows for another tree or another revision, and ignored.
|
|
299
|
+
*
|
|
300
|
+
* Dividing one revision's counters by another's readers is the mistake that
|
|
301
|
+
* would make every rate taken off them quietly wrong.
|
|
302
|
+
*/
|
|
303
|
+
readonly foreign: number;
|
|
304
|
+
/**
|
|
305
|
+
* Rows for this tree and revision, in another audience, and ignored.
|
|
306
|
+
*
|
|
307
|
+
* A page is served in as many forms as it has audiences (0263) and the door
|
|
308
|
+
* counts each one's arrivals on its own row (0284), so a window holding two
|
|
309
|
+
* of them is a deployment doing what it was built to do. It is `foreign` to
|
|
310
|
+
* nothing and `duplicated` to nothing: the other form's readers are real and
|
|
311
|
+
* are simply not the ones this reading is of.
|
|
312
|
+
*/
|
|
313
|
+
readonly otherAudience: number;
|
|
314
|
+
/**
|
|
315
|
+
* Rows for this tree, revision **and audience** beyond the first of that
|
|
316
|
+
* audience, where every one after it was ignored.
|
|
317
|
+
*
|
|
318
|
+
* A store keeps one row per revision per audience, so this cannot happen from
|
|
319
|
+
* one read — it happens when a caller concatenates two. Adding them is wrong,
|
|
320
|
+
* because the openings are already a running total and would double (0158);
|
|
321
|
+
* taking the last is wrong, because it is not the truer one. So the first row
|
|
322
|
+
* of each form stands and the fact is reported.
|
|
323
|
+
*
|
|
324
|
+
* **The audience is part of what makes two rows two rows**, and leaving it
|
|
325
|
+
* out was an undercount (0299): two forms' doors keyed by nothing at all made
|
|
326
|
+
* the second form a repeat of the first, so a deployment-wide reading
|
|
327
|
+
* published one form's arrivals and called the rest a duplicate. A form's own
|
|
328
|
+
* door was never affected — the audience is picked before this, so one form's
|
|
329
|
+
* rows key the same either way.
|
|
330
|
+
*/
|
|
331
|
+
readonly duplicated: number;
|
|
332
|
+
};
|
|
333
|
+
/**
|
|
334
|
+
* A revision of a tree, and the audience the asking is about.
|
|
335
|
+
*
|
|
336
|
+
* The audience is optional and `null` means the same as absent: *this caller
|
|
337
|
+
* did not say*, which reads every form of the page and is what a window
|
|
338
|
+
* written before 0284 and every reading taken before this rule has always
|
|
339
|
+
* done. A caller that names one — which `PageReading` now does for itself —
|
|
340
|
+
* gets that form's door row and nothing else.
|
|
341
|
+
*/
|
|
342
|
+
export type RevisionOf = {
|
|
343
|
+
readonly treeId: TreeId;
|
|
344
|
+
readonly revision: number;
|
|
345
|
+
readonly audienceId?: AudienceId | null;
|
|
346
|
+
};
|
|
347
|
+
/**
|
|
348
|
+
* Read one revision's door out of a window of rows.
|
|
349
|
+
*
|
|
350
|
+
* Linear in the rows, with one pass and one map.
|
|
351
|
+
*/
|
|
352
|
+
export declare const pageViewsFor: (where: RevisionOf, rows: readonly StoredPageViews[]) => PageViewsFor;
|
|
353
|
+
/**
|
|
354
|
+
* The straddle correction for one revision of one page: `drift ÷ opened` off
|
|
355
|
+
* that page's own door — its own form's row where the asking names an audience,
|
|
356
|
+
* and the sum of every form's where it names none (0299).
|
|
357
|
+
*
|
|
358
|
+
* The number `PaceOptions.inflation` wants, published so that a consumer
|
|
359
|
+
* holding a window of counters over several pages does not write the matching
|
|
360
|
+
* itself. `null` where there is no row for the revision, or where nothing has
|
|
361
|
+
* opened — which is *the question has no answer* rather than *the answer is
|
|
362
|
+
* nought*, and is the reason this is not simply `0`.
|
|
363
|
+
*/
|
|
364
|
+
export declare const inflationFor: (where: RevisionOf, rows: readonly StoredPageViews[]) => number | null;
|
|
365
|
+
//# sourceMappingURL=page-views.d.ts.map
|