@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,133 @@
|
|
|
1
|
+
import { everyMemberOf } from "../closed-set.js";
|
|
2
|
+
/** The closed set, in the order a surface reads them: the refusal, then the two quiet states, then the two live ones. */
|
|
3
|
+
export const ARRIVAL_STANDINGS = everyMemberOf()([
|
|
4
|
+
"unasked",
|
|
5
|
+
"silent",
|
|
6
|
+
"turned-away",
|
|
7
|
+
"collecting",
|
|
8
|
+
"mixed",
|
|
9
|
+
]);
|
|
10
|
+
/** The first tally per reason, and how many were dropped. */
|
|
11
|
+
const firstPerReason = (tallies) => {
|
|
12
|
+
const seen = new Set();
|
|
13
|
+
const kept = [];
|
|
14
|
+
let duplicated = 0;
|
|
15
|
+
for (const tally of tallies) {
|
|
16
|
+
if (seen.has(tally.reason)) {
|
|
17
|
+
duplicated += 1;
|
|
18
|
+
continue;
|
|
19
|
+
}
|
|
20
|
+
seen.add(tally.reason);
|
|
21
|
+
kept.push(tally);
|
|
22
|
+
}
|
|
23
|
+
return { kept, duplicated };
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* The newest tally reporting a positive count, or `null` where none does.
|
|
27
|
+
*
|
|
28
|
+
* A reason with a nought is a row that says nothing was turned away for it, so
|
|
29
|
+
* it cannot be the newest thing that was. Ties keep the earlier of the two, so
|
|
30
|
+
* two reasons counted at one instant do not reorder on a refresh.
|
|
31
|
+
*/
|
|
32
|
+
const newestOf = (kept, at) => {
|
|
33
|
+
let newest = null;
|
|
34
|
+
for (const tally of kept) {
|
|
35
|
+
if (tally.refused <= 0)
|
|
36
|
+
continue;
|
|
37
|
+
if (newest === null || tally.lastAt > newest.lastAt)
|
|
38
|
+
newest = tally;
|
|
39
|
+
}
|
|
40
|
+
if (newest === null)
|
|
41
|
+
return null;
|
|
42
|
+
return {
|
|
43
|
+
reason: newest.reason,
|
|
44
|
+
origin: newest.lastOrigin,
|
|
45
|
+
atMs: newest.lastAt,
|
|
46
|
+
sinceMs: at === undefined ? null : at - newest.lastAt,
|
|
47
|
+
};
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* Read a window's health and a door's refusals together, into the one question
|
|
51
|
+
* neither can answer alone.
|
|
52
|
+
*
|
|
53
|
+
* The health is taken as the `Pick` a reading of the window already produced
|
|
54
|
+
* rather than as two loose numbers, so what is judged here is what that reading
|
|
55
|
+
* published, by construction rather than by a reviewer — the shape
|
|
56
|
+
* {@link retentionPromiseOf} takes the retention in (0321). The two fields are
|
|
57
|
+
* the two it needs and the two a caller could most plausibly get wrong by hand:
|
|
58
|
+
* a view floor is not an arrival count (0212), and a count of readers is not a
|
|
59
|
+
* count of pages.
|
|
60
|
+
*
|
|
61
|
+
* **A delivery was turned away if any reason reports a positive count**, which
|
|
62
|
+
* is the one rule the standing turns on, and it is the same rule `newest` is
|
|
63
|
+
* found by — so a standing that names a refusal always carries the refusal it
|
|
64
|
+
* named.
|
|
65
|
+
*
|
|
66
|
+
* **The instant is optional and nothing here reads a clock.** A caller that
|
|
67
|
+
* states one gets `sinceMs` and can tell a live fault from a fixed one; a
|
|
68
|
+
* caller that does not gets every other figure and no age, which is the shape a
|
|
69
|
+
* collection schedule already takes (0274). A reading that read the wall clock
|
|
70
|
+
* would answer differently on two calls over one set of rows.
|
|
71
|
+
*/
|
|
72
|
+
export const arrivalStandingOf = (health, turnedAway, at) => {
|
|
73
|
+
const collected = health.pages.length;
|
|
74
|
+
if (turnedAway === undefined) {
|
|
75
|
+
return {
|
|
76
|
+
standing: "unasked",
|
|
77
|
+
collected,
|
|
78
|
+
arrivals: health.arrivals,
|
|
79
|
+
refused: null,
|
|
80
|
+
newest: null,
|
|
81
|
+
duplicated: 0,
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
const { kept, duplicated } = firstPerReason(turnedAway);
|
|
85
|
+
const newest = newestOf(kept, at);
|
|
86
|
+
const refused = kept.reduce((sum, tally) => sum + tally.refused, 0);
|
|
87
|
+
const standing = collected > 0
|
|
88
|
+
? newest === null
|
|
89
|
+
? "collecting"
|
|
90
|
+
: "mixed"
|
|
91
|
+
: newest === null
|
|
92
|
+
? "silent"
|
|
93
|
+
: "turned-away";
|
|
94
|
+
return { standing, collected, arrivals: health.arrivals, refused, newest, duplicated };
|
|
95
|
+
};
|
|
96
|
+
const versions = (collected) => collected === 1 ? "1 version of 1 page" : `${collected} versions`;
|
|
97
|
+
/** The count and its verb together, because one page view *was* and two *were*. */
|
|
98
|
+
const readers = (arrivals) => arrivals === 1 ? "1 page view was" : `${arrivals} page views were`;
|
|
99
|
+
const deliveries = (refused) => refused === 1 ? "1 delivery was" : `${refused} deliveries were`;
|
|
100
|
+
/** Where the newest refusal came from, named so that `null` is a sentence rather than a blank. */
|
|
101
|
+
const from = (newest) => newest.origin === null
|
|
102
|
+
? `the latest of them ${newest.reason} and naming no site`
|
|
103
|
+
: `the latest of them ${newest.reason}, from ${newest.origin}`;
|
|
104
|
+
/**
|
|
105
|
+
* One line for the operator setting a deployment up, because they are the only
|
|
106
|
+
* person who can close the gap.
|
|
107
|
+
*
|
|
108
|
+
* It names the reason as the deployment spelled it and never translates one: a
|
|
109
|
+
* host's own set is the host's to put a sentence and a remedy to, and a
|
|
110
|
+
* framework that worded them would be wording a vocabulary it does not define.
|
|
111
|
+
*/
|
|
112
|
+
export const describeArrivalStanding = (standing) => {
|
|
113
|
+
switch (standing.standing) {
|
|
114
|
+
case "unasked":
|
|
115
|
+
return ("nothing counted what this door turned away, so a deployment nobody is posting to " +
|
|
116
|
+
"cannot be told from one whose deliveries are being refused");
|
|
117
|
+
case "silent":
|
|
118
|
+
return ("nothing has been collected and nothing has been turned away, " +
|
|
119
|
+
"so no page is posting to this deployment at all");
|
|
120
|
+
case "turned-away":
|
|
121
|
+
return (`nothing has been collected and ${deliveries(standing.refused ?? 0)} turned away, ` +
|
|
122
|
+
`${standing.newest === null ? "with no reason given" : from(standing.newest)}: ` +
|
|
123
|
+
"a page is posting and this door is refusing it");
|
|
124
|
+
case "collecting":
|
|
125
|
+
return (`${readers(standing.arrivals)} counted at the door across ${versions(standing.collected)}, ` +
|
|
126
|
+
"and nothing has been turned away");
|
|
127
|
+
case "mixed":
|
|
128
|
+
return (`${readers(standing.arrivals)} counted at the door across ${versions(standing.collected)}, ` +
|
|
129
|
+
`and ${deliveries(standing.refused ?? 0)} turned away, ` +
|
|
130
|
+
`${standing.newest === null ? "with no reason given" : from(standing.newest)}`);
|
|
131
|
+
}
|
|
132
|
+
};
|
|
133
|
+
//# sourceMappingURL=arriving.js.map
|
|
@@ -0,0 +1,528 @@
|
|
|
1
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
2
|
+
import type { TreeId } from "../ids.js";
|
|
3
|
+
/**
|
|
4
|
+
* Which audience a window of counters is of, and what that makes one reading.
|
|
5
|
+
*
|
|
6
|
+
* [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
|
|
7
|
+
* made a page one base tree plus the deltas an audience earns, composed in the
|
|
8
|
+
* customer's own process per request — so two audiences read **one tree at one
|
|
9
|
+
* revision** and see two forms of it.
|
|
10
|
+
* [0284](../../decisions/0284-a-signal-names-the-audience-it-was-collected-under-and-the-predicate-stays-in-the-control-plane.md)
|
|
11
|
+
* put the audience on all five reader tables and said, in its own consequences,
|
|
12
|
+
* what that leaves undone: *the portal gains a dimension it must not silently
|
|
13
|
+
* collapse*, and *no screen reads this yet*.
|
|
14
|
+
*
|
|
15
|
+
* **The stores keep two audiences apart and every reading folded them back
|
|
16
|
+
* together.** `counters.ts` already has `inAudience` so the memory store cannot
|
|
17
|
+
* merge two rows that Postgres holds apart by its primary key. Nothing above
|
|
18
|
+
* the store had been told: a reading is keyed by a tree and a revision, which
|
|
19
|
+
* two audiences share, so the second audience's rows were dropped as *handed in
|
|
20
|
+
* twice* — the one thing 0158 makes permanent, reported as a fault on a
|
|
21
|
+
* deployment doing exactly what 0263 built.
|
|
22
|
+
*
|
|
23
|
+
* ## Two rules, because a duplicate is whatever the key says it is
|
|
24
|
+
*
|
|
25
|
+
* {@link readingKeyOf} is the first and is the whole of this module's original
|
|
26
|
+
* argument. Readings decide, each in its own loop, whether two readings handed
|
|
27
|
+
* in are one page counted twice; what makes them one is a tree, a revision
|
|
28
|
+
* **and** an audience, and several spellings of that which agree today are the
|
|
29
|
+
* shape this subsystem has been bitten by before (`counters.ts`,
|
|
30
|
+
* `funnelPairKey`). It is published once and imported by every reading that
|
|
31
|
+
* refuses to count a page twice.
|
|
32
|
+
*
|
|
33
|
+
* {@link formKeyOf} is the second, and it is the rule a **comparison** pairs
|
|
34
|
+
* on: a page in one of its forms, with no revision in it, because a comparison
|
|
35
|
+
* spans two revisions of one page. The two are deliberately not one, and the
|
|
36
|
+
* difference is written on {@link PageForm}. It was written in the module that
|
|
37
|
+
* first needed it and kept there, while four other comparisons went on spelling
|
|
38
|
+
* the pairing by tree alone with no key to import (0293) — which is the drift
|
|
39
|
+
* both of these exist to stop, arriving through the one gap a published rule
|
|
40
|
+
* leaves: being published to a single caller.
|
|
41
|
+
*
|
|
42
|
+
* ## Splitting is the caller's, and it is a filter rather than a sum
|
|
43
|
+
*
|
|
44
|
+
* The other half is {@link byAudience}, which turns a window a deployment read
|
|
45
|
+
* into one window per audience. A caller that splits first gets every reading
|
|
46
|
+
* in this subsystem correct with no change to any of them, because each is then
|
|
47
|
+
* handed one population's counters. A caller that does not is not quietly given
|
|
48
|
+
* a number over two populations: `pageReadingOf` reads neither and says which
|
|
49
|
+
* audiences it was handed (`audiences-mixed` in `health.ts`).
|
|
50
|
+
*
|
|
51
|
+
* ## Reading neither is a case, and it was a `null` three readings could ignore
|
|
52
|
+
*
|
|
53
|
+
* {@link AudienceScope} is the third rule, and it exists because the paragraph
|
|
54
|
+
* above was true of one reading and unenforceable on the next. *No audience
|
|
55
|
+
* recorded* is two states — a window written before the column (one population,
|
|
56
|
+
* read whole) and a window of two forms with none asked for (no population,
|
|
57
|
+
* read as neither) — and spelling them as one `null` meant a reading that
|
|
58
|
+
* treated them alike compiled and was wrong only on the deployment doing
|
|
59
|
+
* exactly what 0263 built. The region map's buckets were fixed for it
|
|
60
|
+
* (0297) and the door's arrivals after it (0299), and the third, the funnel,
|
|
61
|
+
* was still taking `matching[0]`.
|
|
62
|
+
* {@link audienceScopeOf} returns the three-way answer and
|
|
63
|
+
* {@link audienceScopeRead} reads it back off a reading that recorded it, so
|
|
64
|
+
* the refusal is a branch a new reading has to write rather than a value it can
|
|
65
|
+
* fall past.
|
|
66
|
+
*
|
|
67
|
+
* ## Comparing is a third question, and the answer it needs is narrower
|
|
68
|
+
*
|
|
69
|
+
* {@link crossesAudiences} is for the comparisons rather than the readings. A
|
|
70
|
+
* before-and-after holds the readership still and varies the tree; a pair whose
|
|
71
|
+
* two sides are of two audiences varies the readership by construction, so the
|
|
72
|
+
* movement it reports carries two causes and nothing in the counters separates
|
|
73
|
+
* them. The rule refuses only a pair that **proves** two populations, because
|
|
74
|
+
* the third state above is real on this side too: a window written before the
|
|
75
|
+
* column existed names no audience, and refusing every pair that spans the
|
|
76
|
+
* migration would withhold the comparison a deployment most wants.
|
|
77
|
+
*
|
|
78
|
+
* ## Comparing two **windows** is a fourth question, and it refuses nothing
|
|
79
|
+
*
|
|
80
|
+
* {@link ComparedPopulations} is for the four library comparisons, whose two
|
|
81
|
+
* sides are whole windows of a deployment's library rather than one reading
|
|
82
|
+
* each. A window holds every form the deployment served, so a side naming two
|
|
83
|
+
* audiences is the ordinary case after 0263 and not a fault — and because
|
|
84
|
+
* those comparisons pair their pages by {@link formKeyOf}, every placement
|
|
85
|
+
* held still is one form's against its own. There is nothing to refuse, and
|
|
86
|
+
* what there is instead is a census: {@link audiencesOf} says whose library
|
|
87
|
+
* each side was, and {@link pagesOf} is what lets a form gained be told from a
|
|
88
|
+
* page published (0295).
|
|
89
|
+
*
|
|
90
|
+
* Nothing here is about a reader. An `aud_` is a name the host chose for a
|
|
91
|
+
* predicate Loom never sees, and splitting on it is grouping rows by a column
|
|
92
|
+
* the host wrote — no payload, no browser, no column and no kind (rule 1).
|
|
93
|
+
*/
|
|
94
|
+
/** A row the store keeps one of per audience (0284). */
|
|
95
|
+
export type AudienceScoped = {
|
|
96
|
+
readonly audienceId: AudienceId;
|
|
97
|
+
};
|
|
98
|
+
/**
|
|
99
|
+
* A row that may or may not name its audience.
|
|
100
|
+
*
|
|
101
|
+
* `ReaderTally` is what a rollup produces and it carries no audience — a rollup
|
|
102
|
+
* folds one audience's window, so the column is on the row the store keeps and
|
|
103
|
+
* not on the counter itself (0284). A reading is therefore handed rows that
|
|
104
|
+
* sometimes name an audience and sometimes cannot, and *cannot* is a third
|
|
105
|
+
* state rather than a default: a hand-built window with no audience anywhere in
|
|
106
|
+
* it is one population by construction, and calling it `aud_everyone` would be
|
|
107
|
+
* asserting something no row said.
|
|
108
|
+
*/
|
|
109
|
+
export type MaybeAudienceScoped = {
|
|
110
|
+
readonly audienceId?: AudienceId;
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* One side of a comparison, as the population rule below needs to see it.
|
|
114
|
+
*
|
|
115
|
+
* Narrower than a reading on purpose: what a comparison has to decide is about
|
|
116
|
+
* the two populations and not about the two pages, so the rule that decides it
|
|
117
|
+
* can be handed a page reading, a funnel reading or a region map without any of
|
|
118
|
+
* them being made to look like the others.
|
|
119
|
+
*/
|
|
120
|
+
export type SideOfAudience = {
|
|
121
|
+
/** `null` or absent where nothing recorded which audience the window was of. */
|
|
122
|
+
readonly audienceId?: AudienceId | null;
|
|
123
|
+
};
|
|
124
|
+
/** A reading, or a row, as the key rule below needs to see it. */
|
|
125
|
+
export type ReadingOfAudience = SideOfAudience & {
|
|
126
|
+
readonly treeId: TreeId;
|
|
127
|
+
readonly revision: number;
|
|
128
|
+
};
|
|
129
|
+
/**
|
|
130
|
+
* The audiences a window names, deduplicated and in a stable order.
|
|
131
|
+
*
|
|
132
|
+
* Rows naming none are not an audience and are not counted as one. A window of
|
|
133
|
+
* them answers `[]`, which is *nothing here says* rather than *one audience* —
|
|
134
|
+
* the distinction `MaybeAudienceScoped` exists for.
|
|
135
|
+
*/
|
|
136
|
+
export declare const audiencesIn: <R extends MaybeAudienceScoped>(rows: readonly R[]) => readonly AudienceId[];
|
|
137
|
+
/**
|
|
138
|
+
* What population a reading is of, as the three answers it can be.
|
|
139
|
+
*
|
|
140
|
+
* The one place that decides it, and the reason it is a type rather than a
|
|
141
|
+
* nullable audience is that **`null` was doing two jobs**. A reading that
|
|
142
|
+
* recorded no audience is either a window of rows written before the column
|
|
143
|
+
* existed (0284) — one population by construction, read whole — or a window
|
|
144
|
+
* holding two forms with none asked for, which is no population at all and
|
|
145
|
+
* must be read as neither (0290). The two states want opposite handling and
|
|
146
|
+
* were spelled as one value, so a reading that forgot to distinguish them did
|
|
147
|
+
* not fail to compile: it fell into the first and read one form's rows as the
|
|
148
|
+
* page's.
|
|
149
|
+
*
|
|
150
|
+
* Three readings here pick a page's rows out of a window, and two of them had
|
|
151
|
+
* already been fixed one at a time — the region map's buckets (0297) and the
|
|
152
|
+
* door's arrivals (0299) — each after publishing a real second form as a count
|
|
153
|
+
* of rows handed in twice. The third was the funnel,
|
|
154
|
+
* where the same `matching[0]` took one form's answer and reported the other's
|
|
155
|
+
* as the same question asked twice. A fourth reading written tomorrow would
|
|
156
|
+
* fall the same way, because nothing in the types asked it the question.
|
|
157
|
+
* {@link AudienceScope} asks it: the `mixed` member is a case to be handled
|
|
158
|
+
* rather than a `null` to be ignored.
|
|
159
|
+
*
|
|
160
|
+
* Every member carries both halves, so a caller that only wants the audience
|
|
161
|
+
* reads `audienceId` without a switch and a caller that must handle the refusal
|
|
162
|
+
* switches on `reading`.
|
|
163
|
+
*/
|
|
164
|
+
export type AudienceScope =
|
|
165
|
+
/**
|
|
166
|
+
* One population: the audience asked for, or the only one the window named.
|
|
167
|
+
*
|
|
168
|
+
* A window naming one audience needs no caller to say so, and an audience
|
|
169
|
+
* asked for scopes the reading whether or not the window holds others — the
|
|
170
|
+
* rest of it is that page's other form, counted apart and not read (0290).
|
|
171
|
+
*/
|
|
172
|
+
{
|
|
173
|
+
readonly reading: "one";
|
|
174
|
+
readonly audienceId: AudienceId;
|
|
175
|
+
/** What the window named, which is not what was asked for. */
|
|
176
|
+
readonly audiences: readonly AudienceId[];
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Nothing in the window named an audience, so it is one population by
|
|
180
|
+
* construction and is read whole.
|
|
181
|
+
*
|
|
182
|
+
* Every window written before the column existed (0284), and every window a
|
|
183
|
+
* caller built by hand. Calling it `aud_everyone` would assert what no row
|
|
184
|
+
* said, which is the distinction {@link MaybeAudienceScoped} exists for.
|
|
185
|
+
*/
|
|
186
|
+
| {
|
|
187
|
+
readonly reading: "unlabelled";
|
|
188
|
+
readonly audienceId: null;
|
|
189
|
+
readonly audiences: readonly [];
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Two or more forms, and the asking named none of them.
|
|
193
|
+
*
|
|
194
|
+
* Read as **neither**. The other two answers available are summing two
|
|
195
|
+
* populations and picking one of them by the caller's array order, and the
|
|
196
|
+
* second is the fault this type exists to make unwritable. Summing is a
|
|
197
|
+
* decision per counter rather than a default: arrivals at the door are
|
|
198
|
+
* counted once per page view and therefore add (0297, 0299), and a distinct
|
|
199
|
+
* count filed against a node does not.
|
|
200
|
+
*/
|
|
201
|
+
| {
|
|
202
|
+
readonly reading: "mixed";
|
|
203
|
+
readonly audienceId: null;
|
|
204
|
+
readonly audiences: readonly AudienceId[];
|
|
205
|
+
};
|
|
206
|
+
/**
|
|
207
|
+
* Which of the three a window and an asking come to.
|
|
208
|
+
*
|
|
209
|
+
* The census is deduplicated and sorted here, so a caller may hand in the rows
|
|
210
|
+
* of two windows concatenated — a reading of funnel rows is of the populations
|
|
211
|
+
* its own rows name **and** of the populations the page reading it was taken
|
|
212
|
+
* against named, and either alone can be the ambiguous one.
|
|
213
|
+
*
|
|
214
|
+
* An audience asked for always wins, including over a window that names it
|
|
215
|
+
* nowhere: a caller asking for one population and being handed none is holding
|
|
216
|
+
* an empty reading, which is what it asked for and not an ambiguity.
|
|
217
|
+
*/
|
|
218
|
+
export declare const audienceScopeOf: (audiences: Iterable<AudienceId>, asked?: AudienceId) => AudienceScope;
|
|
219
|
+
/** A reading that has already recorded which population it was of. */
|
|
220
|
+
export type ReadOfAudience = {
|
|
221
|
+
readonly audienceId: AudienceId | null;
|
|
222
|
+
readonly audiences: readonly AudienceId[];
|
|
223
|
+
};
|
|
224
|
+
/**
|
|
225
|
+
* The scope a reading already recorded, read back off it.
|
|
226
|
+
*
|
|
227
|
+
* What a **second** reading needs: a comparison holding two sides against each
|
|
228
|
+
* other has to know that a side was read as neither population before it can
|
|
229
|
+
* say what moved between them, and a reading that published only its audience
|
|
230
|
+
* and its census leaves that as a subtraction for every caller to make the same
|
|
231
|
+
* way. One of them making it differently is this module's whole subject.
|
|
232
|
+
*/
|
|
233
|
+
export declare const audienceScopeRead: (reading: ReadOfAudience) => AudienceScope;
|
|
234
|
+
/**
|
|
235
|
+
* The rows of one audience, and nothing else.
|
|
236
|
+
*
|
|
237
|
+
* A row naming no audience is not in any audience's window. A caller holding
|
|
238
|
+
* such rows is holding something no store produced, and silently folding them
|
|
239
|
+
* into whichever audience was asked for would be this module inventing the
|
|
240
|
+
* fact it exists to keep.
|
|
241
|
+
*/
|
|
242
|
+
export declare const forAudience: <R extends MaybeAudienceScoped>(audience: AudienceId, rows: readonly R[]) => readonly R[];
|
|
243
|
+
/** One audience's window, as {@link byAudience} hands it over. */
|
|
244
|
+
export type AudienceWindow<R> = {
|
|
245
|
+
readonly audience: AudienceId;
|
|
246
|
+
readonly rows: readonly R[];
|
|
247
|
+
};
|
|
248
|
+
/**
|
|
249
|
+
* A window a deployment read, split into the populations it actually holds.
|
|
250
|
+
*
|
|
251
|
+
* Exhaustive and lossless: every row is in exactly one window, each window's
|
|
252
|
+
* rows keep the order they arrived in, and the windows themselves are in a
|
|
253
|
+
* stable order so two reads of one store produce the same list. A deployment
|
|
254
|
+
* serving one form of every page gets one window, which is what it has always
|
|
255
|
+
* had.
|
|
256
|
+
*/
|
|
257
|
+
export declare const byAudience: <R extends AudienceScoped>(rows: readonly R[]) => readonly AudienceWindow<R>[];
|
|
258
|
+
/**
|
|
259
|
+
* What makes two readings one page: the tree, the revision and the audience.
|
|
260
|
+
*
|
|
261
|
+
* The one place that decides what a duplicate is. Five readings refuse to count
|
|
262
|
+
* a page twice — the health of a collection, the order over a deployment's
|
|
263
|
+
* pages, and the three censuses of a library — and before this they refused on
|
|
264
|
+
* a tree and a revision, which two audiences of one page share. So a deployment
|
|
265
|
+
* that began serving a second form had that form's reading dropped as a repeat
|
|
266
|
+
* of the first, and the number it was dropped out of went on looking right
|
|
267
|
+
* (0158: a count that has been added cannot be unadded, and one that was never
|
|
268
|
+
* added cannot be noticed).
|
|
269
|
+
*
|
|
270
|
+
* A reading naming no audience keys as itself, so a window of rows that never
|
|
271
|
+
* carried the column behaves exactly as it did.
|
|
272
|
+
*/
|
|
273
|
+
export declare const readingKeyOf: (reading: ReadingOfAudience) => string;
|
|
274
|
+
/**
|
|
275
|
+
* A page in one of its forms: the tree and the audience, with no revision in
|
|
276
|
+
* it.
|
|
277
|
+
*
|
|
278
|
+
* Deliberately **not** what {@link readingKeyOf} answers, and the difference is
|
|
279
|
+
* the whole of why there are two rules. That one answers *what is one reading*,
|
|
280
|
+
* and a revision is part of what one reading is (0290). This answers *what is
|
|
281
|
+
* one page in one form*, which a comparison spans two revisions of — so the
|
|
282
|
+
* revision is absent here because it is the thing being compared across.
|
|
283
|
+
*
|
|
284
|
+
* `null` is *nothing recorded which audience this was of*, kept as the third
|
|
285
|
+
* state it is: a window of rows that never carried the column is one population
|
|
286
|
+
* by construction, and keying it as `aud_everyone` would assert what no row
|
|
287
|
+
* said.
|
|
288
|
+
*/
|
|
289
|
+
export type PageForm = {
|
|
290
|
+
readonly treeId: TreeId;
|
|
291
|
+
readonly audienceId: AudienceId | null;
|
|
292
|
+
};
|
|
293
|
+
/** The form a reading is of, with an absent audience normalised to the `null` it means. */
|
|
294
|
+
export declare const formOf: (reading: ReadingOfAudience) => PageForm;
|
|
295
|
+
/**
|
|
296
|
+
* What makes two readings one page in one form, which is what a comparison
|
|
297
|
+
* pairs on.
|
|
298
|
+
*
|
|
299
|
+
* The second of this module's two keys, published for the reason the first is:
|
|
300
|
+
* every comparison in this subsystem decides, in its own loop, whether two
|
|
301
|
+
* readings handed in are one page to be paired or one page handed in twice, and
|
|
302
|
+
* **a tree alone is not that page**. Two forms of it (0263) share a tree, so a
|
|
303
|
+
* comparison keyed by the tree drops the second form as a duplicate where the
|
|
304
|
+
* two sit at one revision and gates **both** out as ambiguous where they do
|
|
305
|
+
* not — which is 0158-permanent in the first case and silent in both.
|
|
306
|
+
*/
|
|
307
|
+
export declare const formKeyOf: (form: PageForm) => string;
|
|
308
|
+
/** Sorted so a list of forms reads the same whatever order they arrived in. */
|
|
309
|
+
export declare const inFormOrder: (one: PageForm, other: PageForm) => number;
|
|
310
|
+
/** The audience each side of a comparison was of, as a comparison carries it. */
|
|
311
|
+
export type ComparedAudiences = {
|
|
312
|
+
readonly was: AudienceId | null;
|
|
313
|
+
readonly now: AudienceId | null;
|
|
314
|
+
};
|
|
315
|
+
/**
|
|
316
|
+
* The two populations a comparison was handed, published once rather than
|
|
317
|
+
* spelled on each comparison.
|
|
318
|
+
*
|
|
319
|
+
* Carried whether or not the pair was refused, because a `null` on either side
|
|
320
|
+
* is the whole of why a mismatched pair can go unrefused: it is what a surface
|
|
321
|
+
* reads to say *this comparison spans a window that named no audience* rather
|
|
322
|
+
* than being told nothing at all.
|
|
323
|
+
*/
|
|
324
|
+
export declare const comparedAudiencesOf: (was: SideOfAudience, now: SideOfAudience) => ComparedAudiences;
|
|
325
|
+
/**
|
|
326
|
+
* Whether two sides of a comparison prove they are of two populations.
|
|
327
|
+
*
|
|
328
|
+
* The one place that decides it, for the reason {@link readingKeyOf} is one
|
|
329
|
+
* place: ten comparisons here take their pair from a caller, nine of them
|
|
330
|
+
* refuse a pair of different trees, and a pair of different audiences is the
|
|
331
|
+
* same kind of error with none of the same visibility. Two trees are two pages and every figure comes back absurd; two
|
|
332
|
+
* forms of one page (0263) compare cleanly and the arithmetic is right. What is
|
|
333
|
+
* wrong is the sentence on top of it — *this is what your change did* — when
|
|
334
|
+
* the readership was varied by construction and the tree may not have changed
|
|
335
|
+
* at all.
|
|
336
|
+
*
|
|
337
|
+
* **False where either side names none, and that is not an oversight.** A row
|
|
338
|
+
* written before the column existed (0284) names no audience, so a pair of such
|
|
339
|
+
* a window and an `aud_pro` one is either an honest before-and-after across the
|
|
340
|
+
* migration or a cross-population comparison, and nothing in the counters tells
|
|
341
|
+
* them apart. Refusing both would withhold every comparison spanning the day a
|
|
342
|
+
* deployment upgraded, which is the comparison it most wants; refusing neither
|
|
343
|
+
* would publish a cross-population movement as a change. So the rule refuses
|
|
344
|
+
* what is provable and {@link comparedAudiencesOf} makes the rest visible.
|
|
345
|
+
*/
|
|
346
|
+
export declare const crossesAudiences: (was: SideOfAudience, now: SideOfAudience) => boolean;
|
|
347
|
+
/**
|
|
348
|
+
* The audiences a set of forms names, deduplicated and in a stable order.
|
|
349
|
+
*
|
|
350
|
+
* The form-level counterpart of {@link audiencesIn}, which answers the same
|
|
351
|
+
* question over rows. A form whose `audienceId` is `null` is not an audience
|
|
352
|
+
* and is not counted as one, so a window of forms that never carried the
|
|
353
|
+
* column answers `[]` — *nothing here says* rather than *one audience*.
|
|
354
|
+
*/
|
|
355
|
+
export declare const audiencesOf: (forms: Iterable<PageForm>) => readonly AudienceId[];
|
|
356
|
+
/**
|
|
357
|
+
* The pages behind a set of forms, which two forms of one page share.
|
|
358
|
+
*
|
|
359
|
+
* A page is one base tree plus the deltas an audience earns (0263), so the
|
|
360
|
+
* tree is the page and the form is the page as one audience meets it. A window
|
|
361
|
+
* of four forms over three trees is three pages, one of them served twice.
|
|
362
|
+
*/
|
|
363
|
+
export declare const pagesOf: (forms: Iterable<PageForm>) => ReadonlySet<TreeId>;
|
|
364
|
+
/**
|
|
365
|
+
* The audiences each side of a **window** comparison was of.
|
|
366
|
+
*
|
|
367
|
+
* Deliberately not {@link ComparedAudiences}, and the difference is the whole
|
|
368
|
+
* reason there are two types. That one is for a comparison whose two sides are
|
|
369
|
+
* one reading each, so each side is of one audience or of none, and a pair
|
|
370
|
+
* naming two is refused ({@link crossesAudiences}). This one is for a
|
|
371
|
+
* comparison whose two sides are whole **windows** of a deployment's library:
|
|
372
|
+
* a window holds every form the deployment served, so after 0263 a side naming
|
|
373
|
+
* two audiences is the ordinary case rather than a fault.
|
|
374
|
+
*
|
|
375
|
+
* Nothing is refused on it. A library comparison pairs its pages by form
|
|
376
|
+
* ({@link formKeyOf}), so every placement held still is one form's measured
|
|
377
|
+
* against its own and no share in such a reading has a denominator spanning two
|
|
378
|
+
* populations. What the two sets are for is the sentence printed over the
|
|
379
|
+
* figures: *this is your library* is a different claim when the window held
|
|
380
|
+
* `aud_skiers` and `aud_riders` than when it held one of them.
|
|
381
|
+
*/
|
|
382
|
+
export type ComparedPopulations = {
|
|
383
|
+
/** The audiences the earlier window's forms named. `[]` where none did. */
|
|
384
|
+
readonly was: readonly AudienceId[];
|
|
385
|
+
/** The audiences the later window's forms named, by the same rule. */
|
|
386
|
+
readonly now: readonly AudienceId[];
|
|
387
|
+
};
|
|
388
|
+
/**
|
|
389
|
+
* Why two readings are not two forms of one page.
|
|
390
|
+
*
|
|
391
|
+
* **Published here rather than on the reading that first needed it**, which is
|
|
392
|
+
* the point of this member existing at all. `formComparisonOf` (0302) spelled
|
|
393
|
+
* these five as its own silences, and a second comparison of two forms wants
|
|
394
|
+
* every one of them with no clause changed: they are facts about the **pair**
|
|
395
|
+
* — one page, two provable populations, one revision — and not about the
|
|
396
|
+
* counter being compared. A second spelling of them would be the fault
|
|
397
|
+
* {@link readingKeyOf} and {@link formKeyOf} exist to stop, one level up: a
|
|
398
|
+
* rule written three times is a rule two of its copies agree with.
|
|
399
|
+
*
|
|
400
|
+
* A reading adds its own members for what its own counter cannot say, and
|
|
401
|
+
* {@link FormPairRefusal} is what it adds them to.
|
|
402
|
+
*/
|
|
403
|
+
export type FormPairRefusal =
|
|
404
|
+
/**
|
|
405
|
+
* The two readings are of different trees.
|
|
406
|
+
*
|
|
407
|
+
* Two pages are two pages, and two audiences do not make them one. Checked
|
|
408
|
+
* first, as every comparison in this subsystem checks it first, because a
|
|
409
|
+
* caller holding two pages wants to be told that before it is told anything
|
|
410
|
+
* about populations.
|
|
411
|
+
*/
|
|
412
|
+
"different-pages"
|
|
413
|
+
/**
|
|
414
|
+
* One of the two windows holds two forms of the page and named neither.
|
|
415
|
+
*
|
|
416
|
+
* The state published as `AudienceScope.mixed` (0290, 0300), and the one
|
|
417
|
+
* refusal here whose remedy is an instruction rather than a fact: **split the
|
|
418
|
+
* window with {@link byAudience} and read each form on its own** — which is
|
|
419
|
+
* exactly what a comparison of two forms then wants as its two sides. A side
|
|
420
|
+
* read as neither form holds no counters at all, so without this every part
|
|
421
|
+
* of the other side would come back as a part only that form has, and the
|
|
422
|
+
* census would read as *the deltas gave this audience the whole page*.
|
|
423
|
+
*
|
|
424
|
+
* Checked before {@link FormPairRefusal.unattributed}, and that order is a
|
|
425
|
+
* real one: one side can be unlabelled while the other is unsplit. The caller
|
|
426
|
+
* is told the one it can do something about.
|
|
427
|
+
*/
|
|
428
|
+
| "unsplit"
|
|
429
|
+
/**
|
|
430
|
+
* One of the two windows named no audience at all.
|
|
431
|
+
*
|
|
432
|
+
* Every window written before the column existed (0284), and every window a
|
|
433
|
+
* caller builds by hand. It is one population read whole, which is the right
|
|
434
|
+
* answer to every other question in this subsystem and is no answer at all to
|
|
435
|
+
* this one: the subject of a form comparison **is** the population, so a side
|
|
436
|
+
* that cannot name its own has nothing to contribute to a comparison of two
|
|
437
|
+
* of them.
|
|
438
|
+
*
|
|
439
|
+
* This is the sharpest difference between a form comparison and a
|
|
440
|
+
* before-and-after. There, a pair with an unlabelled side is compared and
|
|
441
|
+
* merely not provably of one readership (0294), because the audience is a
|
|
442
|
+
* confounder and refusing it would withhold every comparison spanning the
|
|
443
|
+
* migration. Here the audience is the question.
|
|
444
|
+
*/
|
|
445
|
+
| "unattributed"
|
|
446
|
+
/**
|
|
447
|
+
* Both windows name one audience and it is the same one.
|
|
448
|
+
*
|
|
449
|
+
* There is one population and so there is no second form: what the caller is
|
|
450
|
+
* holding is one reading handed in twice, or two windows of one form, and
|
|
451
|
+
* neither is this question. **The only refusal in this subsystem for too few
|
|
452
|
+
* populations rather than too many** — its sibling `two-audiences` refuses a
|
|
453
|
+
* before-and-after for naming two, and the two sit either side of the one
|
|
454
|
+
* thing each reading needs held still.
|
|
455
|
+
*
|
|
456
|
+
* Two windows of one form over two periods is a real question and it is
|
|
457
|
+
* `changeOf`, which is where that caller is sent.
|
|
458
|
+
*/
|
|
459
|
+
| "one-population"
|
|
460
|
+
/**
|
|
461
|
+
* The two readings are of two revisions of the page.
|
|
462
|
+
*
|
|
463
|
+
* The refusal that is a form comparison's whole discipline. Two forms of a
|
|
464
|
+
* page share a tree **and a revision** (0263), so two revisions means the
|
|
465
|
+
* pair varies the tree as well as the readership and every figure would carry
|
|
466
|
+
* both causes with nothing to separate them — which is the one thing a
|
|
467
|
+
* before-and-after is built to avoid and a form comparison would otherwise do
|
|
468
|
+
* silently.
|
|
469
|
+
*
|
|
470
|
+
* Checked after the three population states above, for the reason a form
|
|
471
|
+
* comparison exists: without two provable populations there is no form
|
|
472
|
+
* comparison to refuse on a revision, and a caller told *two revisions* when
|
|
473
|
+
* it is also holding one audience twice would fix the wrong half.
|
|
474
|
+
*/
|
|
475
|
+
| "different-revisions";
|
|
476
|
+
/** The closed set, in the order {@link formPairOf} reaches them. */
|
|
477
|
+
export declare const FORM_PAIR_REFUSALS: readonly FormPairRefusal[];
|
|
478
|
+
/** One line per refusal, for a surface saying why there is no pair. */
|
|
479
|
+
export declare const describeFormPairRefusal: (refusal: FormPairRefusal) => string;
|
|
480
|
+
/** What {@link formPairOf} needs of a side: a page, a revision, and a scope. */
|
|
481
|
+
export type SideOfForm = ReadOfAudience & {
|
|
482
|
+
readonly treeId: TreeId;
|
|
483
|
+
readonly revision: number;
|
|
484
|
+
};
|
|
485
|
+
/**
|
|
486
|
+
* Two readings as a pair of forms, or the reason they are not one.
|
|
487
|
+
*
|
|
488
|
+
* Both members carry the two sides **in the order the pair settled on**, so a
|
|
489
|
+
* refusal is reported about the same two sides a comparison would have been of.
|
|
490
|
+
*/
|
|
491
|
+
export type FormPair<R> = {
|
|
492
|
+
readonly pairing: "paired";
|
|
493
|
+
/** The side whose audience id sorts lower. */
|
|
494
|
+
readonly one: R;
|
|
495
|
+
readonly other: R;
|
|
496
|
+
/** The two names, already in the same order as the two sides. */
|
|
497
|
+
readonly audiences: {
|
|
498
|
+
readonly one: AudienceId;
|
|
499
|
+
readonly other: AudienceId;
|
|
500
|
+
};
|
|
501
|
+
} | {
|
|
502
|
+
readonly pairing: "refused";
|
|
503
|
+
/** The lower-sorting side, or the first argument where no pair of names stands. */
|
|
504
|
+
readonly one: R;
|
|
505
|
+
readonly other: R;
|
|
506
|
+
readonly refusal: FormPairRefusal;
|
|
507
|
+
};
|
|
508
|
+
/**
|
|
509
|
+
* Settle two readings into two forms of one page, or say why they are not.
|
|
510
|
+
*
|
|
511
|
+
* **Neither side is earlier, so the order of the arguments does not reach the
|
|
512
|
+
* answer.** `changeOf` takes `was` and `now` and does not check which is older:
|
|
513
|
+
* a caller holding them backwards gets every sign reversed, which is the
|
|
514
|
+
* bargain 0224 struck so that *this week against last week* comes out of the
|
|
515
|
+
* same function. Here that bargain would be a bug rather than a trade, because
|
|
516
|
+
* there is no fact of the matter about which of two populations comes first.
|
|
517
|
+
* Two deployments asking one question would get two answers, and a screen built
|
|
518
|
+
* on one of them would read the direction of every figure backwards without
|
|
519
|
+
* anything saying so.
|
|
520
|
+
*
|
|
521
|
+
* So the two sides are put in the order of their audience ids **before anything
|
|
522
|
+
* is read off either**, and `one` is the lower of the two names rather than the
|
|
523
|
+
* first argument. A pair with a name missing on either side has no order to
|
|
524
|
+
* take and keeps the arguments' own, which is all the two refusals that have no
|
|
525
|
+
* second population need.
|
|
526
|
+
*/
|
|
527
|
+
export declare const formPairOf: <R extends SideOfForm>(one: R, other: R) => FormPair<R>;
|
|
528
|
+
//# sourceMappingURL=audiences.d.ts.map
|