@jam-overture/loom 0.2.0 → 0.3.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/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/resolve.d.ts +1 -1
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +192 -46
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/gate.js +69 -10
- package/dist/runtime/index.d.ts +1 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/policy-change.js +8 -2
- package/dist/runtime/policy-log.d.ts +5 -5
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/sdk/definition.d.ts +65 -6
- package/dist/sdk/definition.js +44 -0
- package/dist/sdk/registry.d.ts +17 -1
- package/dist/sdk/registry.js +39 -0
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/broadcast.d.ts +25 -15
- package/dist/signals/broadcast.js +209 -36
- package/dist/signals/collect.d.ts +137 -43
- package/dist/signals/collect.js +103 -36
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +51 -0
- package/dist/signals/counters.js +58 -0
- package/dist/signals/deployment-change.d.ts +28 -4
- package/dist/signals/deployment-change.js +57 -16
- package/dist/signals/deployment.d.ts +18 -5
- package/dist/signals/deployment.js +37 -11
- package/dist/signals/door.d.ts +34 -12
- package/dist/signals/door.js +37 -13
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +60 -0
- package/dist/signals/funnel.js +35 -20
- package/dist/signals/health.d.ts +201 -4
- package/dist/signals/health.js +214 -2
- package/dist/signals/index.d.ts +19 -0
- package/dist/signals/index.js +19 -0
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +112 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-reach-change.d.ts +10 -0
- package/dist/signals/library-reach-change.js +11 -3
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.js +2 -6
- package/dist/signals/memory.js +142 -1
- package/dist/signals/migrate.d.ts +6 -5
- package/dist/signals/migrate.js +150 -6
- package/dist/signals/notice.d.ts +88 -33
- package/dist/signals/notice.js +38 -16
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +25 -15
- package/dist/signals/parts.js +32 -73
- package/dist/signals/postgres.js +400 -26
- package/dist/signals/region.d.ts +1 -1
- package/dist/signals/retention.d.ts +43 -21
- package/dist/signals/retention.js +25 -8
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +127 -1
- package/dist/signals/rollup.js +211 -24
- package/dist/signals/schema.d.ts +640 -3
- package/dist/signals/schema.js +239 -3
- package/dist/signals/silences.d.ts +310 -11
- package/dist/signals/silences.js +243 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +125 -4
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +11 -0
- package/dist/store/index.js +11 -0
- package/dist/store/migrate.d.ts +26 -0
- package/dist/store/migrate.js +64 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres.d.ts +1 -0
- package/dist/store/postgres.js +1 -0
- package/dist/store/schema.d.ts +312 -0
- package/dist/store/schema.js +77 -0
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +32 -0
- package/dist/telemetry/memory.js +10 -1
- package/dist/telemetry/postgres.js +18 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +1 -0
- package/dist/testing/contracts.js +1 -0
- package/dist/testing/journal-contract.js +158 -5
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/tree/apply.js +13 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/package.json +39 -96
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
package/dist/signals/collect.js
CHANGED
|
@@ -3,32 +3,41 @@ import { clampLimit } from "../paging.js";
|
|
|
3
3
|
import { systemClock } from "../runtime/events.js";
|
|
4
4
|
import { rollUp } from "./rollup.js";
|
|
5
5
|
/**
|
|
6
|
-
* The one operation that
|
|
6
|
+
* The one operation that counts the buffer.
|
|
7
7
|
*
|
|
8
8
|
* `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
|
|
9
9
|
* keep what the fold produced — and until this module existed nothing joined
|
|
10
10
|
* the three, so a deployment with signals switched on accumulated the largest
|
|
11
11
|
* table it owns and counted none of it.
|
|
12
12
|
*
|
|
13
|
-
* **Counting and
|
|
14
|
-
* convenience.** A rollup reports *what this window
|
|
15
|
-
* counted twice is counted twice forever: there is no
|
|
16
|
-
* on and no way to notice afterwards, because the
|
|
17
|
-
* like a busy afternoon. The only defence that does
|
|
18
|
-
* is for the set of batches rolled up and the set
|
|
19
|
-
* decided once, in one place. That is
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
13
|
+
* **Counting and recording that it happened are one call, and that is the
|
|
14
|
+
* design rather than a convenience.** A rollup reports *what this window
|
|
15
|
+
* added* (0147), so a batch counted twice is counted twice forever: there is no
|
|
16
|
+
* idempotence to fall back on and no way to notice afterwards, because the
|
|
17
|
+
* wrong number looks exactly like a busy afternoon. The only defence that does
|
|
18
|
+
* not need durable bookkeeping is for the set of batches rolled up and the set
|
|
19
|
+
* marked as counted to be the same set, decided once, in one place. That is
|
|
20
|
+
* this file.
|
|
21
|
+
*
|
|
22
|
+
* **Until 5 November the mark was a delete** (0146), and the sentence above
|
|
23
|
+
* said *forgotten* where it now says *marked*. A delivery is now kept for the
|
|
24
|
+
* window its deployment states — thirty days by default, so that an operator
|
|
25
|
+
* can look at individual deliveries rather than only at counters (0349) — and
|
|
26
|
+
* deleted by a second sweep in `expire.ts`. What did not change is the thing
|
|
27
|
+
* the invariant protects: this run decides one prefix, counts it, and records
|
|
28
|
+
* that it counted it, and no other operation may touch that decision. What that
|
|
29
|
+
* split buys is that the two failures are no longer the same failure. A sweep
|
|
30
|
+
* that deletes without counting loses deliveries; this cannot delete at all.
|
|
23
31
|
*
|
|
24
32
|
* Nothing schedules it, for the reason nothing schedules telemetry's retention
|
|
25
|
-
* or `auditSnapshot`: when a deployment
|
|
26
|
-
* framework that quietly
|
|
27
|
-
* making it. A host calls this from a cron route, a deploy hook, or by hand
|
|
33
|
+
* or `auditSnapshot`: when a deployment counts is an operational choice, and a
|
|
34
|
+
* framework that quietly swept a host's data on a timer it chose would be
|
|
35
|
+
* making it. A host calls this from a cron route, a deploy hook, or by hand,
|
|
36
|
+
* and calls {@link expireReaderEvents} from the same place.
|
|
28
37
|
*
|
|
29
38
|
* **One run at a time, and the caller is what makes that true.** Two runs over
|
|
30
39
|
* the same ripe prefix both roll it up and both apply; applying is additive
|
|
31
|
-
* (0147), so the counters double and the
|
|
40
|
+
* (0147), so the counters double and the prefix is marked once, leaving nothing
|
|
32
41
|
* behind that could say what happened. Nothing here can prevent it — a journal
|
|
33
42
|
* and a store are two handles with no shared transaction between them — so
|
|
34
43
|
* serialising belongs to whatever schedules this. `apps/loom/scripts/
|
|
@@ -36,8 +45,8 @@ import { rollUp } from "./rollup.js";
|
|
|
36
45
|
* cheapest thing that works for a cron that overruns its own interval.
|
|
37
46
|
*/
|
|
38
47
|
/**
|
|
39
|
-
* The window is the age a batch reaches before it is counted and
|
|
40
|
-
*
|
|
48
|
+
* The window is the age a batch reaches before it is counted, and it is two
|
|
49
|
+
* arguments pulling opposite ways.
|
|
41
50
|
*
|
|
42
51
|
* **Longer is more accurate.** `views` and `reached` count distinct page views,
|
|
43
52
|
* distinctness does not add up, and a page view whose batches straddle two
|
|
@@ -55,10 +64,15 @@ import { rollUp } from "./rollup.js";
|
|
|
55
64
|
* allows — the openings waiting are otherwise indistinguishable from the
|
|
56
65
|
* ordinary one-window lag this setting creates (0274).
|
|
57
66
|
*
|
|
58
|
-
* **Shorter is more anonymous
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
67
|
+
* **Shorter is more anonymous — and since 5 November this is no longer the
|
|
68
|
+
* window that governs that.** The view key stops existing when the row holding
|
|
69
|
+
* it is deleted, and that is now the kept window rather than this one
|
|
70
|
+
* (0349, 0351): a delivery is counted at this age and deleted at the age
|
|
71
|
+
* `expire.ts` is given. This setting still decides how much over-count a
|
|
72
|
+
* straddling page view causes, which is the accuracy argument above; what it no
|
|
73
|
+
* longer decides is how long a page view's signals stay correlatable. That
|
|
74
|
+
* number is `DEFAULT_READER_EVENT_RETENTION_MS` and the tension in it is
|
|
75
|
+
* recorded rather than hidden.
|
|
62
76
|
*
|
|
63
77
|
* An hour is long against a page view and short against a day, which is why it
|
|
64
78
|
* is the default rather than a constant: rule 5 of `docs/signals.md` makes the
|
|
@@ -101,6 +115,27 @@ export const collectionPlanOf = (scanned, horizon) => {
|
|
|
101
115
|
waiting: scanned.length - ripe.length,
|
|
102
116
|
};
|
|
103
117
|
};
|
|
118
|
+
/**
|
|
119
|
+
* The pairs a run folding a window that **begins** at `from` may ask, and the
|
|
120
|
+
* count of the ones it may not.
|
|
121
|
+
*
|
|
122
|
+
* The comparison is against the oldest delivery in the window rather than
|
|
123
|
+
* against the run's own clock, and that is the whole of the rule: every
|
|
124
|
+
* delivery this run folds arrived at or after `from`, so a question whose start
|
|
125
|
+
* is at or before `from` is answered over readers who all arrived after it was
|
|
126
|
+
* asked. A question asked in the middle of a window is held back one run, which
|
|
127
|
+
* costs one window of an answer and buys a figure that means what its label
|
|
128
|
+
* says.
|
|
129
|
+
*
|
|
130
|
+
* **An unreadable instant withholds every question with a start**, because the
|
|
131
|
+
* fallback is the one that cannot be noticed: counting a step from a window
|
|
132
|
+
* nobody can place is a figure nobody can date.
|
|
133
|
+
*/
|
|
134
|
+
export const funnelsAskedOf = (pairs, from) => {
|
|
135
|
+
const begins = Date.parse(from);
|
|
136
|
+
const asking = pairs.filter(({ countedFrom }) => countedFrom === undefined || (Number.isFinite(begins) && countedFrom <= begins));
|
|
137
|
+
return { asking, withheld: pairs.length - asking.length };
|
|
138
|
+
};
|
|
104
139
|
export const horizonOf = (configured, now) => {
|
|
105
140
|
const instant = Date.parse(now);
|
|
106
141
|
return Number.isFinite(instant) ? new Date(instant - configured.windowMs).toISOString() : null;
|
|
@@ -111,6 +146,12 @@ export const horizonOf = (configured, now) => {
|
|
|
111
146
|
* Every batch from the horizon on is too young to count, and `collectionPlanOf`
|
|
112
147
|
* needs only the first of them to know where the ripe prefix ends — so reading
|
|
113
148
|
* further would be reading the busiest part of the table to throw it away.
|
|
149
|
+
*
|
|
150
|
+
* **Uncounted rows only** (0351), which is what makes the oldest end of the
|
|
151
|
+
* table the oldest *uncounted* delivery rather than the oldest kept one. Without
|
|
152
|
+
* it this scan would read the whole kept window — thirty days by default — to
|
|
153
|
+
* reach the handful of rows a run is for, and the cost of collecting would grow
|
|
154
|
+
* with a setting that has nothing to do with collecting.
|
|
114
155
|
*/
|
|
115
156
|
const scanFrom = async (journal, horizon, scanLimit) => {
|
|
116
157
|
const collected = [];
|
|
@@ -118,6 +159,7 @@ const scanFrom = async (journal, horizon, scanLimit) => {
|
|
|
118
159
|
while (collected.length < scanLimit) {
|
|
119
160
|
const page = await journal.read({
|
|
120
161
|
direction: "newer",
|
|
162
|
+
counted: false,
|
|
121
163
|
limit: Math.min(SCAN_PAGE, scanLimit - collected.length),
|
|
122
164
|
...(cursor ? { cursor } : {}),
|
|
123
165
|
});
|
|
@@ -134,11 +176,12 @@ const scanFrom = async (journal, horizon, scanLimit) => {
|
|
|
134
176
|
return { ok: true, batches: collected, full: true };
|
|
135
177
|
};
|
|
136
178
|
/**
|
|
137
|
-
* Count a window of the buffer into the durable counters, then
|
|
179
|
+
* Count a window of the buffer into the durable counters, then record that it
|
|
180
|
+
* was counted.
|
|
138
181
|
*
|
|
139
182
|
* The order is the safe one and the reverse is a data-loss bug that looks like
|
|
140
|
-
* a feature working: aggregates first, the
|
|
141
|
-
* `counted-not-
|
|
183
|
+
* a feature working: aggregates first, the mark second. What that leaves is
|
|
184
|
+
* `counted-not-recorded`, which is visible and recoverable — the opposite
|
|
142
185
|
* order's failure is neither.
|
|
143
186
|
*/
|
|
144
187
|
export const collectReaderSignals = async (journal, store, request = {}) => {
|
|
@@ -186,10 +229,6 @@ export const collectReaderSignals = async (journal, store, request = {}) => {
|
|
|
186
229
|
else
|
|
187
230
|
group.push(batch);
|
|
188
231
|
}
|
|
189
|
-
const folded = [...byAudience].map(([audience, batches]) => ({
|
|
190
|
-
audience,
|
|
191
|
-
rollup: rollUp(batches, { ...(request.pairs ? { pairs: request.pairs } : {}) }),
|
|
192
|
-
}));
|
|
193
232
|
/**
|
|
194
233
|
* The oldest delivery in the buffer, which is the first batch the scan read:
|
|
195
234
|
* it runs from the oldest end and the ripe prefix starts there.
|
|
@@ -202,10 +241,23 @@ export const collectReaderSignals = async (journal, store, request = {}) => {
|
|
|
202
241
|
* not a number makes it answer that nothing here can say.
|
|
203
242
|
*/
|
|
204
243
|
const oldest = plan.ripe[0]?.receivedAt ?? "";
|
|
244
|
+
/**
|
|
245
|
+
* The questions this window is old enough to answer, decided once for the
|
|
246
|
+
* whole run (0418) — every audience's fold asks the same ones, because a
|
|
247
|
+
* start is a fact about when somebody asked and not about who read.
|
|
248
|
+
*/
|
|
249
|
+
const { asking, withheld } = funnelsAskedOf(request.pairs ?? [], oldest);
|
|
250
|
+
const folded = [...byAudience].map(([audience, batches]) => ({
|
|
251
|
+
audience,
|
|
252
|
+
rollup: rollUp(batches, { ...(asking.length > 0 ? { pairs: asking } : {}) }),
|
|
253
|
+
}));
|
|
205
254
|
const summary = {
|
|
206
255
|
counted: plan.ripe.length,
|
|
256
|
+
withheldFunnels: withheld,
|
|
207
257
|
oldestMs: Date.parse(now) - Date.parse(oldest),
|
|
208
258
|
tallies: folded.reduce((total, { rollup }) => total + rollup.tallies.length, 0),
|
|
259
|
+
acted: folded.reduce((total, { rollup }) => total + rollup.acted.length, 0),
|
|
260
|
+
funnelHours: folded.reduce((total, { rollup }) => total + rollup.funnelHours.length, 0),
|
|
209
261
|
funnels: folded.reduce((total, { rollup }) => total + rollup.funnels.length, 0),
|
|
210
262
|
views: folded.reduce((total, { rollup }) => total + rollup.views, 0),
|
|
211
263
|
uncorrelated: folded.reduce((total, { rollup }) => total + rollup.uncorrelated, 0),
|
|
@@ -232,22 +284,29 @@ export const collectReaderSignals = async (journal, store, request = {}) => {
|
|
|
232
284
|
tallies: rollup.tallies,
|
|
233
285
|
funnels: rollup.funnels,
|
|
234
286
|
appearances: rollup.appearances,
|
|
287
|
+
acted: rollup.acted,
|
|
288
|
+
funnelHours: rollup.funnelHours,
|
|
235
289
|
})), now);
|
|
236
290
|
if (!applied.ok)
|
|
237
291
|
return { outcome: "unavailable", error: applied.error };
|
|
238
|
-
|
|
239
|
-
|
|
292
|
+
/**
|
|
293
|
+
* The same instant the counters were written with, so one run leaves one
|
|
294
|
+
* instant across both halves of what it did — and the instant a reading of
|
|
295
|
+
* the fold's lag is taken against is the instant the fold actually happened.
|
|
296
|
+
*/
|
|
297
|
+
const recorded = await journal.counted({ before: plan.before, at: now });
|
|
298
|
+
if (!recorded.ok) {
|
|
240
299
|
return {
|
|
241
|
-
outcome: "counted-not-
|
|
300
|
+
outcome: "counted-not-recorded",
|
|
242
301
|
summary,
|
|
243
302
|
before: plan.before,
|
|
244
|
-
error:
|
|
303
|
+
error: recorded.error,
|
|
245
304
|
};
|
|
246
305
|
}
|
|
247
306
|
return {
|
|
248
307
|
outcome: "collected",
|
|
249
308
|
summary,
|
|
250
|
-
|
|
309
|
+
recorded: recorded.value.counted,
|
|
251
310
|
more: scanned.full,
|
|
252
311
|
};
|
|
253
312
|
};
|
|
@@ -259,15 +318,23 @@ const uncorrelated = (summary) => summary.uncorrelated === 0 ? "" : `, ${summary
|
|
|
259
318
|
* operator to stop reading it.
|
|
260
319
|
*/
|
|
261
320
|
const redelivered = (summary) => summary.redelivered === 0 ? "" : `, ${summary.redelivered} delivered again and folded once`;
|
|
321
|
+
/**
|
|
322
|
+
* Said only when there were some, like the two above, and said as *this window
|
|
323
|
+
* is too old for them* rather than as a refusal: the questions are fine and the
|
|
324
|
+
* next window answers them (0418).
|
|
325
|
+
*/
|
|
326
|
+
const withheldFunnels = (summary) => summary.withheldFunnels === 0
|
|
327
|
+
? ""
|
|
328
|
+
: `, ${summary.withheldFunnels} ${summary.withheldFunnels === 1 ? "funnel" : "funnels"} not asked of a window older than them`;
|
|
262
329
|
/** One line for an operator, because an outcome nobody can read is one nobody acts on. */
|
|
263
330
|
export const describeCollection = (outcome) => {
|
|
264
331
|
switch (outcome.outcome) {
|
|
265
332
|
case "collected":
|
|
266
|
-
return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}${redelivered(outcome.summary)}, and
|
|
333
|
+
return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}${redelivered(outcome.summary)}${withheldFunnels(outcome.summary)}, and marked ${outcome.recorded} counted${outcome.more ? " — more is waiting" : ""}`;
|
|
267
334
|
case "nothing-ripe":
|
|
268
335
|
return `nothing old enough to count${outcome.waiting === 0 ? "" : `, ${batches(outcome.waiting)} waiting`}`;
|
|
269
|
-
case "counted-not-
|
|
270
|
-
return `counted ${batches(outcome.summary.counted)} and could not
|
|
336
|
+
case "counted-not-recorded":
|
|
337
|
+
return `counted ${batches(outcome.summary.counted)} and could not record it, so the next run counts them again unless they are marked counted below ${outcome.before}: ${outcome.error.detail}`;
|
|
271
338
|
case "refused":
|
|
272
339
|
return `collection refused: ${outcome.reason}`;
|
|
273
340
|
case "unavailable":
|
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
2
|
+
import type { TreeId } from "../ids.js";
|
|
3
|
+
import type { FunnelReach, PairReach } from "./funnel.js";
|
|
4
|
+
/**
|
|
5
|
+
* Which of a deployment's pages loses the most readers between an ask and its
|
|
6
|
+
* answer.
|
|
7
|
+
*
|
|
8
|
+
* A deployment can already ask where its readers stop reading, and the pages
|
|
9
|
+
* come back in one order with the worst of them named
|
|
10
|
+
* ([0250](../../decisions/0250-a-deployment-is-ordered-by-readers-lost-at-the-doors-scale-and-a-page-the-door-cannot-scale-is-out-of-the-order.md)).
|
|
11
|
+
* It could not ask where its readers stop **converting**, and the two are not
|
|
12
|
+
* the same question: a pricing band every reader reaches and nobody buys from
|
|
13
|
+
* has no fall in it anywhere, so the order of falls says *nothing to do here*
|
|
14
|
+
* about the half of a page that pays.
|
|
15
|
+
*
|
|
16
|
+
* This is that second order, over the funnel answers a deployment already has:
|
|
17
|
+
* no payload field, no counter, no column, no byte on any wire and no figure a
|
|
18
|
+
* funnel reading does not already publish.
|
|
19
|
+
*
|
|
20
|
+
* ## It ranks the loss between the two ends and never the loss before them
|
|
21
|
+
*
|
|
22
|
+
* A funnel answer holds two losses. Readers who never reached the first end are
|
|
23
|
+
* `before`, and readers who reached it and did not finish are `between`
|
|
24
|
+
* (0221, 0229). **Only the second is ranked here**, and that is the whole of
|
|
25
|
+
* what keeps this order and the order of falls from being two spellings of one
|
|
26
|
+
* list: a reader who never reached the ask stopped *reading*, which is where
|
|
27
|
+
* the fall between two siblings already puts them, and a page whose readers
|
|
28
|
+
* stop short of the pricing band would otherwise stand near the head of both
|
|
29
|
+
* orders for one event.
|
|
30
|
+
*
|
|
31
|
+
* So the key is `reached − converted`, put on the scale that page's own door
|
|
32
|
+
* counts in by `atDoorScale`, because the straddle rate is each page's own and
|
|
33
|
+
* ranking the raw losses would rank partly by how long readers stay (0219).
|
|
34
|
+
*
|
|
35
|
+
* ## The key is a ceiling, and the floor beside it is published
|
|
36
|
+
*
|
|
37
|
+
* That key is the **most** the leak could be rather than an estimate of it. The
|
|
38
|
+
* straddle inflates both counts of the subtraction and scaling puts that back,
|
|
39
|
+
* but a straddle also splits a conversion across two windows and **loses** it
|
|
40
|
+
* (0147) — and no division puts back a count that was never made. So
|
|
41
|
+
* {@link LeakingPage.readers} is a ceiling, {@link LeakingPage.readersAtLeast}
|
|
42
|
+
* is the floor underneath it, and the two meet wherever nobody's visit spanned
|
|
43
|
+
* two windows. Both come off {@link PairLeak}, which is where the bounds the
|
|
44
|
+
* funnel already published are joined to the door's scale.
|
|
45
|
+
*
|
|
46
|
+
* What the floor buys is the one sentence this order could not say before: *this
|
|
47
|
+
* page is losing at least this many readers, however short your rollup window
|
|
48
|
+
* is.* It is also what makes {@link DeploymentConversion.worstSecure}
|
|
49
|
+
* answerable — whether the page named first is first however the straddle fell,
|
|
50
|
+
* which a ranking on a ceiling alone cannot say.
|
|
51
|
+
*
|
|
52
|
+
* ## One argument, because the funnel answer already carries the door
|
|
53
|
+
*
|
|
54
|
+
* The order of falls takes the door rows beside the readings, since a reading
|
|
55
|
+
* of where reading stops holds no arrivals. A funnel answer holds both — it is
|
|
56
|
+
* read against the exact number of readers the revision had — so this is one
|
|
57
|
+
* call with one argument and there is no row set to match up wrongly.
|
|
58
|
+
*
|
|
59
|
+
* ## A page nobody asked anything of is not a page nobody answered
|
|
60
|
+
*
|
|
61
|
+
* Nine states keep a page out of the order and each is a different sentence.
|
|
62
|
+
* Three are the door's (0229); one is the caller's window holding two forms and
|
|
63
|
+
* naming neither (0300); one is a question nobody has reached; one is a count
|
|
64
|
+
* that cannot be reconciled with the page views there were to hold it; one is
|
|
65
|
+
* the page that leaks nobody; and **two are about the questions a deployment
|
|
66
|
+
* wrote rather than about any measurement** — a revision with no funnel
|
|
67
|
+
* question at all, and a revision all of whose questions name parts it no
|
|
68
|
+
* longer has (0212). No reading before this one could report either of those
|
|
69
|
+
* two, because no reading before this one was keyed by what a deployment asked.
|
|
70
|
+
*
|
|
71
|
+
* ## What is deliberately not published
|
|
72
|
+
*
|
|
73
|
+
* **No deployment-wide conversion rate.** The artefact is an order and not a
|
|
74
|
+
* total: a rate over several pages would need a denominator across them, and
|
|
75
|
+
* the readers of two pages are two populations whose funnel answers are added
|
|
76
|
+
* across rollup windows and therefore generous (0147). Every reader figure here
|
|
77
|
+
* is one page's own, on that page's own row.
|
|
78
|
+
*
|
|
79
|
+
* The one figure that is added is `arrivals`, addable for the reason every
|
|
80
|
+
* other counter here is not: a page view began on exactly one revision of
|
|
81
|
+
* exactly one tree, was counted once at the door, and is never recounted
|
|
82
|
+
* (0219). The counts of questions add for the same kind of reason — a question
|
|
83
|
+
* belongs to one revision of one page.
|
|
84
|
+
*
|
|
85
|
+
* Pure, linear in the readings times their pairs, and reaches no store, clock
|
|
86
|
+
* or DOM.
|
|
87
|
+
*/
|
|
88
|
+
/** A reason a page's conversion loss is withheld rather than ranked. */
|
|
89
|
+
export type ConversionSilence =
|
|
90
|
+
/**
|
|
91
|
+
* The reading holds two forms of the page and named neither, so it read
|
|
92
|
+
* neither population's answers.
|
|
93
|
+
*
|
|
94
|
+
* Checked before everything else, because it is the cause of the noughts
|
|
95
|
+
* underneath it: two forms of a page share a tree and a revision (0263) and
|
|
96
|
+
* are told apart by a column (0284), so a funnel answer handed both with
|
|
97
|
+
* neither asked for reads no pair at all — which is indistinguishable from a
|
|
98
|
+
* page nothing asks anything of, and would be published as one (0301).
|
|
99
|
+
*
|
|
100
|
+
* The remedy is the caller's and it is the only one here that is: split the
|
|
101
|
+
* window by audience and read each form on its own.
|
|
102
|
+
*/
|
|
103
|
+
"unsplit"
|
|
104
|
+
/**
|
|
105
|
+
* There is no page-view row at the door for this revision, so its loss cannot
|
|
106
|
+
* be put on the same scale as another page's.
|
|
107
|
+
*
|
|
108
|
+
* Not a page that was not measured. Every figure inside its funnel answer
|
|
109
|
+
* stands; what is missing is the one number that makes two pages comparable.
|
|
110
|
+
*/
|
|
111
|
+
| "unscaled"
|
|
112
|
+
/**
|
|
113
|
+
* The row is there and nothing in it says a page view ever began.
|
|
114
|
+
*
|
|
115
|
+
* Either nobody read this revision, or the senders are not marking their
|
|
116
|
+
* openings — and the reading publishes both counts, so the diagnosis is a
|
|
117
|
+
* subtraction a surface can make.
|
|
118
|
+
*/
|
|
119
|
+
| "unopened"
|
|
120
|
+
/** Readers arrived and no rollup has folded a window of their reading yet. */
|
|
121
|
+
| "uncounted"
|
|
122
|
+
/**
|
|
123
|
+
* Every question this revision is asked names a part it no longer has.
|
|
124
|
+
*
|
|
125
|
+
* Removed by a change, renamed, or moved to another tree: the counts against
|
|
126
|
+
* those ends cannot move again and the noughts they report are not reader
|
|
127
|
+
* facts (0212). **The sentence a surface should print is not about readers at
|
|
128
|
+
* all** — it is *re-point these questions* — which is why this is held apart
|
|
129
|
+
* from a funnel nobody answered.
|
|
130
|
+
*
|
|
131
|
+
* Reported only where **every** question is stale. A revision with one sound
|
|
132
|
+
* question and three stale ones is ranked on the sound one, with the three
|
|
133
|
+
* counted on the row.
|
|
134
|
+
*/
|
|
135
|
+
| "stale"
|
|
136
|
+
/**
|
|
137
|
+
* Nobody reached the start of any question this revision is asked.
|
|
138
|
+
*
|
|
139
|
+
* The questions name parts the page has and no reader has got to one of them
|
|
140
|
+
* in this window. There is no conversion to lose rather than a conversion
|
|
141
|
+
* everybody failed, and the two print as opposite sentences.
|
|
142
|
+
*/
|
|
143
|
+
| "unanswered"
|
|
144
|
+
/**
|
|
145
|
+
* More readers reached its sharpest ask than have ever appeared on the page.
|
|
146
|
+
*
|
|
147
|
+
* No rollup produces this: a view that satisfied an end in a window is a view
|
|
148
|
+
* that appeared in it. A funnel row older than the page-view column, or a
|
|
149
|
+
* caller that concatenated two reads of the counters, does. The counts are
|
|
150
|
+
* published and the scaled figure is withheld, because the scale is the part
|
|
151
|
+
* that is not true.
|
|
152
|
+
*/
|
|
153
|
+
| "inconsistent";
|
|
154
|
+
export declare const CONVERSION_SILENCES: readonly ConversionSilence[];
|
|
155
|
+
/**
|
|
156
|
+
* One line per silence, for a surface saying why a page has no funnel figure.
|
|
157
|
+
*
|
|
158
|
+
* **The sentences are the order's own, moved here rather than written again.**
|
|
159
|
+
* Every member of this set is also a {@link ConversionStanding}, and
|
|
160
|
+
* {@link describeConversionStanding} has had a line for each since the order
|
|
161
|
+
* was built — so a second spelling of *no page views counted at the door* would
|
|
162
|
+
* be the thing this subsystem's census of silences exists to stop, one module
|
|
163
|
+
* in. The standing now defers to this for the seven it shares, which is why the
|
|
164
|
+
* text below is unchanged from what that function returned.
|
|
165
|
+
*
|
|
166
|
+
* The condition's own sentence — `describeSilenceCondition` in
|
|
167
|
+
* [`silences.ts`](silences.ts) — is the third and is not a replacement for
|
|
168
|
+
* either: it is the wording shared across every reading here, for a card
|
|
169
|
+
* speaking about two readings at once.
|
|
170
|
+
*/
|
|
171
|
+
export declare const describeConversionSilence: (silence: ConversionSilence) => string;
|
|
172
|
+
/** Where one page stands in the order, or why it is not in it. */
|
|
173
|
+
export type ConversionStanding =
|
|
174
|
+
/** In the order, by the readers it loses between the two ends of its sharpest ask. */
|
|
175
|
+
"ranked"
|
|
176
|
+
/**
|
|
177
|
+
* Every reader who reached one of its asks went on to answer it.
|
|
178
|
+
*
|
|
179
|
+
* The cheerful answer, and a thin window produces it as well: two readers who
|
|
180
|
+
* both converted leak nobody either. The arrivals travel with the row, so the
|
|
181
|
+
* two are told apart on the row rather than by this word.
|
|
182
|
+
*/
|
|
183
|
+
| "unleaked"
|
|
184
|
+
/**
|
|
185
|
+
* Nothing asks this version of the page for anything.
|
|
186
|
+
*
|
|
187
|
+
* **Not a silence**, which is the distinction worth keeping: no figure is
|
|
188
|
+
* being withheld, because no question was written. A deployment reading it is
|
|
189
|
+
* being told that the page has no funnel to measure rather than that its
|
|
190
|
+
* funnel could not be measured, and those are opposite instructions.
|
|
191
|
+
*/
|
|
192
|
+
| "unasked" | ConversionSilence;
|
|
193
|
+
export declare const CONVERSION_STANDINGS: readonly ConversionStanding[];
|
|
194
|
+
/** One line per standing, for a surface naming why a page is where it is. */
|
|
195
|
+
export declare const describeConversionStanding: (standing: ConversionStanding) => string;
|
|
196
|
+
/** One revision of one page, as the order of conversions has it. */
|
|
197
|
+
export type LeakingPage = {
|
|
198
|
+
readonly treeId: TreeId;
|
|
199
|
+
readonly revision: number;
|
|
200
|
+
/**
|
|
201
|
+
* The audience this row is about, or `null` where the reading named none.
|
|
202
|
+
*
|
|
203
|
+
* Two forms of one page stand here as two rows, as they do in the order of
|
|
204
|
+
* falls (0250): both are live, both are asked the same question, and the two
|
|
205
|
+
* answers are of two populations. Nothing is summed across them.
|
|
206
|
+
*/
|
|
207
|
+
readonly audienceId: AudienceId | null;
|
|
208
|
+
readonly standing: ConversionStanding;
|
|
209
|
+
/** Page views counted at the door, exact, or `null` where this revision has no row. */
|
|
210
|
+
readonly opened: number | null;
|
|
211
|
+
/** This page's own straddle rate, which is what scales its loss. */
|
|
212
|
+
readonly inflation: number | null;
|
|
213
|
+
/** How many questions this revision is asked, as the reading read them. */
|
|
214
|
+
readonly questions: number;
|
|
215
|
+
/** Of those, how many name a part this revision no longer has. */
|
|
216
|
+
readonly stalePairs: number;
|
|
217
|
+
/**
|
|
218
|
+
* The ask that loses the most readers between its two ends, carried whole and
|
|
219
|
+
* unchanged.
|
|
220
|
+
*
|
|
221
|
+
* `null` where no question of this revision could be ranked — which is every
|
|
222
|
+
* standing but `ranked`, `unleaked` and `inconsistent`.
|
|
223
|
+
*/
|
|
224
|
+
readonly at: PairReach | null;
|
|
225
|
+
/** Readers lost between that ask's two ends, as the window's counters have it. */
|
|
226
|
+
readonly lost: number | null;
|
|
227
|
+
/**
|
|
228
|
+
* The same loss on the door's scale, which is the key the order is on, and
|
|
229
|
+
* the **most** that loss could be.
|
|
230
|
+
*
|
|
231
|
+
* Not a count of people and not rounded into one. Withheld where the page has
|
|
232
|
+
* no rankable question, or no row to scale one by.
|
|
233
|
+
*
|
|
234
|
+
* It is {@link PairLeak.atMost} carried through unchanged, so the figure this
|
|
235
|
+
* order ranks on and the figure the funnel answer publishes cannot come to
|
|
236
|
+
* disagree.
|
|
237
|
+
*/
|
|
238
|
+
readonly readers: number | null;
|
|
239
|
+
/**
|
|
240
|
+
* The least that loss could be, given the straddle this page's own door
|
|
241
|
+
* measured.
|
|
242
|
+
*
|
|
243
|
+
* {@link PairLeak.atLeast}, carried through on the same terms as
|
|
244
|
+
* {@link LeakingPage.readers}: both or neither. It equals `readers` wherever
|
|
245
|
+
* nobody's visit spanned two windows, and falls away from it as a
|
|
246
|
+
* deployment's rollup window shortens relative to how long its readers stay.
|
|
247
|
+
*
|
|
248
|
+
* The figure to print where a page's measurement is under suspicion: a
|
|
249
|
+
* `counts-inflated` deployment (0336) has every conversion key withdrawn from
|
|
250
|
+
* its order, and this one number is the part of it a straddle cannot have
|
|
251
|
+
* manufactured.
|
|
252
|
+
*/
|
|
253
|
+
readonly readersAtLeast: number | null;
|
|
254
|
+
/**
|
|
255
|
+
* Of the readers who reached that ask, the share that answered it, carried
|
|
256
|
+
* through from the pair unchanged.
|
|
257
|
+
*
|
|
258
|
+
* Sound without any correction, because both of its counts come off the same
|
|
259
|
+
* row — so it is published even for a page whose scaled figure is withheld as
|
|
260
|
+
* inconsistent.
|
|
261
|
+
*/
|
|
262
|
+
readonly rate: number | null;
|
|
263
|
+
};
|
|
264
|
+
/** A deployment's pages, in the order their conversions should be looked at. */
|
|
265
|
+
export type DeploymentConversion = {
|
|
266
|
+
/**
|
|
267
|
+
* Every page with a leak and a scale for it, worst first.
|
|
268
|
+
*
|
|
269
|
+
* Most readers lost at the door's scale, then the worse rate, then by tree id
|
|
270
|
+
* and newest revision first — so two pages that leak the same do not reorder
|
|
271
|
+
* on a refresh.
|
|
272
|
+
*/
|
|
273
|
+
readonly ranked: readonly LeakingPage[];
|
|
274
|
+
/** Every other page, by tree id and newest revision first. */
|
|
275
|
+
readonly unranked: readonly LeakingPage[];
|
|
276
|
+
/** The head of the order, which is the funnel to look at first. */
|
|
277
|
+
readonly worst: LeakingPage | null;
|
|
278
|
+
/**
|
|
279
|
+
* Whether the page named {@link DeploymentConversion.worst} is first however
|
|
280
|
+
* the straddle fell: its floor is at or above every other ranked page's
|
|
281
|
+
* ceiling.
|
|
282
|
+
*
|
|
283
|
+
* The order is on a ceiling, so two pages whose intervals overlap could be
|
|
284
|
+
* either way round and the order has to pick one. This says whether that pick
|
|
285
|
+
* was forced. `true` where nothing can overtake the head — including the
|
|
286
|
+
* order of one, where there is nothing to overtake it — `false` where the next
|
|
287
|
+
* page's ceiling reaches the head's floor, and `null` where no page is ranked
|
|
288
|
+
* at all.
|
|
289
|
+
*
|
|
290
|
+
* One comparison rather than a second order, and deliberately so: ranking on
|
|
291
|
+
* the floor instead would be a different key for the same question, and the key
|
|
292
|
+
* is the one the record that built this order named. What a surface does with a
|
|
293
|
+
* `false` is say so — *these two are too close to call at your rollup window* —
|
|
294
|
+
* which is a truer sentence than either order alone.
|
|
295
|
+
*/
|
|
296
|
+
readonly worstSecure: boolean | null;
|
|
297
|
+
/** How many pages stand in each state, over the ranked and the unranked alike. */
|
|
298
|
+
readonly standings: Readonly<Record<ConversionStanding, number>>;
|
|
299
|
+
/**
|
|
300
|
+
* Distinct trees across every page read, which is not the number of pages.
|
|
301
|
+
*
|
|
302
|
+
* Two revisions of one tree are two live versions of one page and both stand
|
|
303
|
+
* in the order, as they do in the order of falls (0250).
|
|
304
|
+
*/
|
|
305
|
+
readonly trees: number;
|
|
306
|
+
/**
|
|
307
|
+
* Page views counted at the door across the pages handed in, added.
|
|
308
|
+
*
|
|
309
|
+
* Exact and addable, for the reason no other figure here is: a page view
|
|
310
|
+
* began on one revision of one tree and was counted once (0219). It is a
|
|
311
|
+
* weight rather than a deployment total — this sees the pages its caller
|
|
312
|
+
* read, not the deployment's.
|
|
313
|
+
*/
|
|
314
|
+
readonly arrivals: number;
|
|
315
|
+
/**
|
|
316
|
+
* Funnel questions across the pages handed in, added.
|
|
317
|
+
*
|
|
318
|
+
* A question belongs to one revision of one page in one form, so two pages'
|
|
319
|
+
* questions are two questions even where both name the same two ends: the
|
|
320
|
+
* same ask of two pages has two answers.
|
|
321
|
+
*/
|
|
322
|
+
readonly questions: number;
|
|
323
|
+
/** Of those, how many name a part the revision asking them no longer has. */
|
|
324
|
+
readonly stalePairs: number;
|
|
325
|
+
/**
|
|
326
|
+
* Readings of a revision beyond the first, which were dropped.
|
|
327
|
+
*
|
|
328
|
+
* A caller that concatenated two reads holds one page twice, and a page twice
|
|
329
|
+
* in an order is the one way an order can lie about how much there is to fix
|
|
330
|
+
* (0158).
|
|
331
|
+
*/
|
|
332
|
+
readonly duplicated: number;
|
|
333
|
+
};
|
|
334
|
+
/**
|
|
335
|
+
* A deployment's pages, in the order their funnels should be looked at.
|
|
336
|
+
*
|
|
337
|
+
* ```ts
|
|
338
|
+
* const assembly = windowAssemblyOf(window, context)
|
|
339
|
+
* const order = deploymentConversionOf(windowFunnelsOf(window, assembly).pages)
|
|
340
|
+
* ```
|
|
341
|
+
*
|
|
342
|
+
* Takes the funnel answers rather than the counters, for the reason every
|
|
343
|
+
* derived reading in this subsystem takes readings: each answer is separately
|
|
344
|
+
* useful and separately drawn, and deriving one twice is how two screens come
|
|
345
|
+
* to disagree about one page.
|
|
346
|
+
*/
|
|
347
|
+
export declare const deploymentConversionOf: (funnels: readonly FunnelReach[]) => DeploymentConversion;
|
|
348
|
+
//# sourceMappingURL=conversion.d.ts.map
|