@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/tally.d.ts
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
import type { AudienceId } from "../audience/audience.js";
|
|
2
|
-
import type { TreeId } from "../ids.js";
|
|
2
|
+
import type { NodeId, TreeId } from "../ids.js";
|
|
3
3
|
import type { Result } from "../result.js";
|
|
4
|
+
import type { ActedHourCount, StoredActed } from "./acted.js";
|
|
5
|
+
import type { FunnelHourCount, StoredFunnelHours } from "./funnel-hours.js";
|
|
6
|
+
import type { StoredArrivals } from "./arrivals.js";
|
|
4
7
|
import type { ReaderSignalStoreError } from "./journal.js";
|
|
5
8
|
import type { RevisionViews, StoredPageViews } from "./page-views.js";
|
|
6
|
-
import type { FunnelAnswer, ReaderTally } from "./rollup.js";
|
|
9
|
+
import type { FunnelAnswer, FunnelPair, ReaderTally } from "./rollup.js";
|
|
7
10
|
/**
|
|
8
11
|
* Where the counters live once the batches they came from are gone.
|
|
9
12
|
*
|
|
@@ -68,7 +71,7 @@ export type TallyReadRequest = {
|
|
|
68
71
|
* apart groups rather than summing — and a caller that sums two has asked
|
|
69
72
|
* for one number about two populations.
|
|
70
73
|
*/
|
|
71
|
-
readonly audience?: AudienceId;
|
|
74
|
+
readonly audience?: AudienceId | undefined;
|
|
72
75
|
/**
|
|
73
76
|
* Absent reads every revision.
|
|
74
77
|
*
|
|
@@ -96,6 +99,14 @@ export interface ReaderOpeningCounter {
|
|
|
96
99
|
* Additive like everything else in this file, and for the sharpest reason of
|
|
97
100
|
* any of them: every call is one delivery's worth of arrivals, so a store
|
|
98
101
|
* that replaced would report the last reader rather than the readership.
|
|
102
|
+
*
|
|
103
|
+
* **It writes two rows for every opening: the revision's total and the hour
|
|
104
|
+
* it arrived in** (`arrivals.ts`), in one atomic write. One call rather than
|
|
105
|
+
* two because the two numbers are the same arrivals counted under two keys,
|
|
106
|
+
* and a door that could move one without the other would be a deployment
|
|
107
|
+
* whose hourly chart does not sum to its own page-view count — for ever,
|
|
108
|
+
* invisibly, with no way to tell which of the two is the wrong one. `at` is
|
|
109
|
+
* the hour, so the second row needs nothing this call did not already have.
|
|
99
110
|
*/
|
|
100
111
|
readonly opened: (openings: readonly RevisionViews[], at: string,
|
|
101
112
|
/**
|
|
@@ -137,11 +148,42 @@ export type AppliedCounters = {
|
|
|
137
148
|
* make a reading claim the node counters were exact.
|
|
138
149
|
*/
|
|
139
150
|
readonly appearances?: readonly RevisionViews[];
|
|
151
|
+
/**
|
|
152
|
+
* The same window's occurrences of the three delegated kinds, filed under the
|
|
153
|
+
* hour the door received them in (`acted.ts`).
|
|
154
|
+
*
|
|
155
|
+
* Optional on the same terms as `appearances`, and absent is not none: a
|
|
156
|
+
* caller composing counters by hand has no receive instants to file them
|
|
157
|
+
* under, and rows of noughts would claim that readers did nothing in an hour
|
|
158
|
+
* nothing was measured in.
|
|
159
|
+
*
|
|
160
|
+
* **Written in the same transaction as the tallies it slices**, because the
|
|
161
|
+
* two numbers a reading divides have to describe the same window — and
|
|
162
|
+
* because the hours of a part are expected to sum to the part's own counters
|
|
163
|
+
* for every window folded since the table existed.
|
|
164
|
+
*/
|
|
165
|
+
readonly acted?: readonly ActedHourCount[];
|
|
166
|
+
/**
|
|
167
|
+
* The same window's funnel answers, cut into the hours the views in each of
|
|
168
|
+
* them entered the funnel (`funnel-hours.ts`).
|
|
169
|
+
*
|
|
170
|
+
* Optional on the same terms as the two above, and absent is not none: a
|
|
171
|
+
* caller composing counters by hand has no receive instants to file a cohort
|
|
172
|
+
* under, and rows of noughts would claim that nobody entered a funnel in an
|
|
173
|
+
* hour nothing was measured in.
|
|
174
|
+
*
|
|
175
|
+
* **Written in the same transaction as the answers it slices**, because the
|
|
176
|
+
* hours of a pair are expected to sum to the pair's own row for every window
|
|
177
|
+
* folded since the table existed — and a slice that moved while the row it
|
|
178
|
+
* slices did not is a chart that cannot be reconciled with the figure beside
|
|
179
|
+
* it.
|
|
180
|
+
*/
|
|
181
|
+
readonly funnelHours?: readonly FunnelHourCount[];
|
|
140
182
|
};
|
|
141
183
|
/** One audience's share of a window, which is what {@link ReaderTallyStore.applyWindow} takes a list of. */
|
|
142
184
|
export type AudienceCounters = AppliedCounters & {
|
|
143
185
|
/** The audience this fold was taken over (0284). Omitted is `aud_everyone`. */
|
|
144
|
-
readonly audience?: AudienceId;
|
|
186
|
+
readonly audience?: AudienceId | undefined;
|
|
145
187
|
};
|
|
146
188
|
export interface ReaderTallyStore extends ReaderOpeningCounter {
|
|
147
189
|
/**
|
|
@@ -195,5 +237,84 @@ export interface ReaderTallyStore extends ReaderOpeningCounter {
|
|
|
195
237
|
* screen needs and the only row here written from two sides.
|
|
196
238
|
*/
|
|
197
239
|
readonly pageViews: (request?: TallyReadRequest) => Promise<Result<readonly StoredPageViews[], ReaderSignalStoreError>>;
|
|
240
|
+
/**
|
|
241
|
+
* The same page views, by the hour they began in, over a range (`arrivals.ts`).
|
|
242
|
+
*
|
|
243
|
+
* The one read here that takes a stretch of time, because it is the one
|
|
244
|
+
* counter that has one. It answers two things in a call — the hours in the
|
|
245
|
+
* range, and the first hour this scope ever counted — so that a surface
|
|
246
|
+
* drawing a chart over a range the deployment is younger than can say so
|
|
247
|
+
* instead of drawing it empty.
|
|
248
|
+
*/
|
|
249
|
+
readonly arrivals: (request?: ArrivalReadRequest) => Promise<Result<StoredArrivals, ReaderSignalStoreError>>;
|
|
250
|
+
/**
|
|
251
|
+
* What readers did, per part, by the hour they did it in, over a range
|
|
252
|
+
* (`acted.ts`).
|
|
253
|
+
*
|
|
254
|
+
* The second read here that takes a stretch of time, and the second that
|
|
255
|
+
* answers two things in a call — the rows in the range, and the first hour
|
|
256
|
+
* this scope ever counted — so a goal's figure over thirty days on a
|
|
257
|
+
* deployment that has counted for a week says so instead of drawing a fall.
|
|
258
|
+
*/
|
|
259
|
+
readonly acted: (request?: ActedReadRequest) => Promise<Result<StoredActed, ReaderSignalStoreError>>;
|
|
260
|
+
/**
|
|
261
|
+
* A funnel pair's answers, by the hour the readers in each entered it, over a
|
|
262
|
+
* range (`funnel-hours.ts`).
|
|
263
|
+
*
|
|
264
|
+
* The third read here that takes a stretch of time, and the third that
|
|
265
|
+
* answers two things in a call — the rows in the range, and the first hour
|
|
266
|
+
* this scope ever counted — so a step compared over two fortnights on a
|
|
267
|
+
* deployment that has counted for a week says so rather than reporting that
|
|
268
|
+
* the step was invented this morning.
|
|
269
|
+
*
|
|
270
|
+
* **The pair narrows it like a part narrows the read above**, and for a
|
|
271
|
+
* sharper reason than cost: `reached` is a distinct count of page views, so
|
|
272
|
+
* rows of two pairs sharing a first end hold the same view twice and a figure
|
|
273
|
+
* summed across them counts that reader once per question. A caller reads one
|
|
274
|
+
* pair, or groups what it got by the pair on each row.
|
|
275
|
+
*/
|
|
276
|
+
readonly funnelHours: (request?: FunnelHourReadRequest) => Promise<Result<StoredFunnelHours, ReaderSignalStoreError>>;
|
|
198
277
|
}
|
|
278
|
+
/**
|
|
279
|
+
* A counter read, narrowed to a stretch of time.
|
|
280
|
+
*
|
|
281
|
+
* The three optional narrowings every counter read takes, and the range. Both
|
|
282
|
+
* ends are optional and absent is *unbounded on that side*: a surface asking
|
|
283
|
+
* when counting began passes neither, and a chart passes both. Hours are
|
|
284
|
+
* matched by the instant they began, which is the rule `ArrivalRange` states —
|
|
285
|
+
* a bucket belongs to the range its start falls in.
|
|
286
|
+
*/
|
|
287
|
+
export type ArrivalReadRequest = TallyReadRequest & {
|
|
288
|
+
/** Inclusive. Absent reads from the first hour the scope has. */
|
|
289
|
+
readonly from?: number;
|
|
290
|
+
/** Exclusive. Absent reads to the last hour the scope has. */
|
|
291
|
+
readonly to?: number;
|
|
292
|
+
};
|
|
293
|
+
/**
|
|
294
|
+
* The same read, narrowed to one part as well.
|
|
295
|
+
*
|
|
296
|
+
* A goal is a kind on a part (0350), so the reading that serves one names the
|
|
297
|
+
* part and the store answers it from an index rather than by reading the rest
|
|
298
|
+
* of the page. Absent reads every part the narrowing holds, which is *what
|
|
299
|
+
* readers did on this page* — the bars the wireframe puts in the `By page`
|
|
300
|
+
* drawer.
|
|
301
|
+
*/
|
|
302
|
+
export type ActedReadRequest = ArrivalReadRequest & {
|
|
303
|
+
readonly nodeId?: NodeId;
|
|
304
|
+
};
|
|
305
|
+
/**
|
|
306
|
+
* The same read, narrowed to one funnel as well.
|
|
307
|
+
*
|
|
308
|
+
* A pair is two ends a deployment wrote down (0418), and the store answers it
|
|
309
|
+
* from an index rather than by reading the other questions the deployment
|
|
310
|
+
* asks. Absent reads every pair the narrowing holds, which is the honest shape
|
|
311
|
+
* for an operator listing what a window held — and the shape a figure must
|
|
312
|
+
* **not** be summed over, for the reason {@link ReaderTallyStore.funnelHours}
|
|
313
|
+
* gives. `pages` on the pair is ignored: a scope decides which rows are
|
|
314
|
+
* written and is not part of what a row means, so it cannot narrow a read of
|
|
315
|
+
* one (0418).
|
|
316
|
+
*/
|
|
317
|
+
export type FunnelHourReadRequest = ArrivalReadRequest & {
|
|
318
|
+
readonly pair?: FunnelPair;
|
|
319
|
+
};
|
|
199
320
|
//# sourceMappingURL=tally.d.ts.map
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
2
|
+
import type { TreeId } from "../ids.js";
|
|
3
|
+
import { type PageFrontier, type UnreachedPart } from "./frontier.js";
|
|
4
|
+
/**
|
|
5
|
+
* **The places a deployment's readers stopped, by what one fix recovers.**
|
|
6
|
+
*
|
|
7
|
+
* [`frontier.ts`](frontier.ts) reads one page as the places its reading stopped
|
|
8
|
+
* ([0374](../../decisions/0374-a-pages-unread-parts-are-reported-as-the-places-its-reading-stopped-and-each-is-behind-exactly-one.md)):
|
|
9
|
+
* a part no view reported reaching whose containing part was reached, with every
|
|
10
|
+
* unreached part behind exactly one of them. This is that reading at the
|
|
11
|
+
* deployment's scale — **an order over the pages, and an order over the places
|
|
12
|
+
* across all of them** — so *where in this deployment should somebody go and
|
|
13
|
+
* look* is a question about a list rather than about nine screens opened one at
|
|
14
|
+
* a time.
|
|
15
|
+
*
|
|
16
|
+
* ## The count it exists instead of
|
|
17
|
+
*
|
|
18
|
+
* `PageReading.standings`' `skipped` counts a band, the rows inside it, the
|
|
19
|
+
* cells inside those and every heading among them: one band nobody reached,
|
|
20
|
+
* counted once per node underneath it. **Two pages with one unread band each are
|
|
21
|
+
* ordered by how deeply each band happens to nest**, which is a fact about the
|
|
22
|
+
* markup and not about the readers — and the figure looks right the whole way,
|
|
23
|
+
* which is what makes it the worst kind of wrong on a fix-list.
|
|
24
|
+
*
|
|
25
|
+
* So nothing here is ranked on it. The key is {@link PageUnread.costs}: the
|
|
26
|
+
* parts of the page that **one** place accounts for, which is what one fix
|
|
27
|
+
* recovers. A page whose pricing band went unseen is one row costing nineteen
|
|
28
|
+
* parts, and a page with nineteen unread footnotes at the top level is nineteen
|
|
29
|
+
* rows costing one each — and the first is the page to go and look at, which is
|
|
30
|
+
* the order the count of parts gets backwards.
|
|
31
|
+
*
|
|
32
|
+
* Both figures are published, side by side and never added: *this deployment has
|
|
33
|
+
* four hundred and twelve unread parts in nine places* is the sentence, and the
|
|
34
|
+
* second number is the one an operator's afternoon is spent on.
|
|
35
|
+
*
|
|
36
|
+
* ## Ranked by the sharpest place and not by the page's total
|
|
37
|
+
*
|
|
38
|
+
* A page's whole unread count is on its reading already
|
|
39
|
+
* ({@link PageFrontier.unseen}) and is deliberately not the key. The precedent
|
|
40
|
+
* is the order of falls, which ranks a page by its **steepest** fall and not by
|
|
41
|
+
* everything it loses
|
|
42
|
+
* ([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)):
|
|
43
|
+
* a fix-list is a list of things somebody will do one of, so the figure it is
|
|
44
|
+
* ordered by has to be what doing one of them is worth. Ranking on the total
|
|
45
|
+
* would put a page with ten small scattered places above a page with one large
|
|
46
|
+
* one, and send an operator to the page where their afternoon buys least.
|
|
47
|
+
*
|
|
48
|
+
* ## It publishes no reader count, and that is the rule rather than an omission
|
|
49
|
+
*
|
|
50
|
+
* Every figure here is a count of **parts of pages** or of **pages**, and not one
|
|
51
|
+
* of readers. The orders beside this one are in readers — readers lost at a fall
|
|
52
|
+
* (0250), readers lost between two ends of a question (0333), the readers a
|
|
53
|
+
* fault costs (0271) — and a part is none of those things. So nothing here is
|
|
54
|
+
* ranked against them, summed with them, or carried into them: the refusal
|
|
55
|
+
* [0327](../../decisions/0327-the-figures-a-window-holds-about-itself-are-a-second-rung-and-a-region-row-set-is-deduplicated-once.md)
|
|
56
|
+
* makes about adding figures in different units, applied to a fourth unit.
|
|
57
|
+
*
|
|
58
|
+
* **The fix-list's own `first` is unchanged for the same reason.** This order
|
|
59
|
+
* stands beside `DeploymentAgenda.page` the way `DeploymentAgenda.converting`
|
|
60
|
+
* stands beside it, and which of them a screen opens with is the screen's
|
|
61
|
+
* judgement — not a comparison this file is in a position to make.
|
|
62
|
+
*
|
|
63
|
+
* ## The two states that must not read as *every part of this page was read*
|
|
64
|
+
*
|
|
65
|
+
* The reading of a page nobody opened is **empty**, and so is the reading of a
|
|
66
|
+
* page every part of which was reached. Those are opposite sentences with one
|
|
67
|
+
* shape, and a page read as neither of its two forms (0290, 0300) produces the
|
|
68
|
+
* same empty reading a third way. So a page is never in this order on the
|
|
69
|
+
* strength of an absence: {@link UnreadStanding} asks what the emptiness was,
|
|
70
|
+
* and `whole` is the only member that means what it looks like.
|
|
71
|
+
*
|
|
72
|
+
* The sharpest of the four is a reading whose rows name nodes the revision does
|
|
73
|
+
* not contain. That pair reads as *a page every reader stopped at the very top
|
|
74
|
+
* of*, which is the most plausible-looking output this reading has, so it is
|
|
75
|
+
* `mismatched`, it is out of the order, and its figures are withheld rather than
|
|
76
|
+
* drawn (0212's alarm, carried through {@link PageFrontier.orphaned}).
|
|
77
|
+
*
|
|
78
|
+
* ## A part that said nothing with a reader below it is a different sentence
|
|
79
|
+
*
|
|
80
|
+
* {@link DeploymentUnread.notReporting} is a **slice** of the rows and not a
|
|
81
|
+
* list beside them, so nothing here is counted twice (0158). It is separate
|
|
82
|
+
* because the instruction is: a part a reader was demonstrably below and which
|
|
83
|
+
* said nothing about itself is a primitive that does not spread the identity
|
|
84
|
+
* attributes a broadcaster reads — `sdk/conformance.ts`' failure — and so it is
|
|
85
|
+
* a fix in the library rather than a page to rewrite. No fault vocabulary gains
|
|
86
|
+
* a member for it here: a fault nobody has seen in the wild is a name invented
|
|
87
|
+
* ahead of its reader.
|
|
88
|
+
*
|
|
89
|
+
* Pure, linear in the readings handed in, and reaches no store, clock, registry
|
|
90
|
+
* or DOM. Nothing is added to any payload, any table or any browser: a place the
|
|
91
|
+
* reading stopped is derived from the tree the counters already name, which is
|
|
92
|
+
* what [0167](../../decisions/0167-a-delegated-signal-names-the-regions-it-happened-inside.md)
|
|
93
|
+
* refused to put on the wire for exactly these kinds.
|
|
94
|
+
*/
|
|
95
|
+
/** Where one page stands in the order of places, or why it is not in it. */
|
|
96
|
+
export type UnreadStanding =
|
|
97
|
+
/** In the order, with at least one place the reading stopped and a sound pair behind it. */
|
|
98
|
+
"ranked"
|
|
99
|
+
/**
|
|
100
|
+
* Every part of the page was reached by somebody.
|
|
101
|
+
*
|
|
102
|
+
* The cheerful answer, and the only member that means what an empty reading
|
|
103
|
+
* looks like. A thin window reaches it honestly as well — a revision four
|
|
104
|
+
* readers saw the whole of has nothing unread — and `views` on the reading is
|
|
105
|
+
* what tells the two apart.
|
|
106
|
+
*/
|
|
107
|
+
| "whole"
|
|
108
|
+
/**
|
|
109
|
+
* Nothing reported a view of this revision in the window, so nothing can be
|
|
110
|
+
* said about any part of it.
|
|
111
|
+
*
|
|
112
|
+
* Not `whole`. *Nobody opened this page* and *every part of this page was
|
|
113
|
+
* read* are opposite facts with one shape, and guessing the second is the
|
|
114
|
+
* comforting half of a pair this subsystem has been bitten by before.
|
|
115
|
+
*/
|
|
116
|
+
| "unread"
|
|
117
|
+
/**
|
|
118
|
+
* One window holds two forms of the page and the asking named neither, so it
|
|
119
|
+
* is read as neither.
|
|
120
|
+
*
|
|
121
|
+
* Every part is `unknown` and the reading is empty while the counters behind
|
|
122
|
+
* it are full (0290, 0300). The remedy is `byAudience` and two reads, and the
|
|
123
|
+
* census on the reading says which two.
|
|
124
|
+
*/
|
|
125
|
+
| "unsplit"
|
|
126
|
+
/**
|
|
127
|
+
* The reading names nodes this revision does not contain, so the tree and the
|
|
128
|
+
* window do not belong together.
|
|
129
|
+
*
|
|
130
|
+
* Out of the order and its figures withheld. This is the reading that looks
|
|
131
|
+
* most plausible when the pair is wrong — revision 7's counters against
|
|
132
|
+
* revision 6's tree leaves most parts reporting nothing, which reads as a page
|
|
133
|
+
* every reader stopped at the top of — so a surface should name it rather than
|
|
134
|
+
* draw it (0212).
|
|
135
|
+
*/
|
|
136
|
+
| "mismatched";
|
|
137
|
+
export declare const UNREAD_STANDINGS: readonly UnreadStanding[];
|
|
138
|
+
/** One line per standing, for a surface naming why a page is where it is. */
|
|
139
|
+
export declare const describeUnreadStanding: (standing: UnreadStanding) => string;
|
|
140
|
+
/** One revision of one page, as the order of places has it. */
|
|
141
|
+
export type PageUnread = {
|
|
142
|
+
readonly treeId: TreeId;
|
|
143
|
+
readonly revision: number;
|
|
144
|
+
/**
|
|
145
|
+
* The audience this row is about, or `null` where the reading named none.
|
|
146
|
+
*
|
|
147
|
+
* Two forms of one page stand here as two rows, for the reason they do in
|
|
148
|
+
* every order in this subsystem: both are live, both have readers, and the
|
|
149
|
+
* parts one form's readers never reached are not the parts the other's never
|
|
150
|
+
* reached (0300).
|
|
151
|
+
*/
|
|
152
|
+
readonly audienceId: AudienceId | null;
|
|
153
|
+
readonly standing: UnreadStanding;
|
|
154
|
+
/** The page's frontier reading, carried whole and unchanged. */
|
|
155
|
+
readonly reading: PageFrontier;
|
|
156
|
+
/**
|
|
157
|
+
* The place one fix recovers the most of this page at, or `null` where the
|
|
158
|
+
* order did not rank it.
|
|
159
|
+
*
|
|
160
|
+
* The head of {@link largestUnreachedIn} for this page, taken from that call
|
|
161
|
+
* rather than chosen again here — one rule for *which place is worst*, in the
|
|
162
|
+
* module that publishes the places.
|
|
163
|
+
*/
|
|
164
|
+
readonly at: UnreachedPart | null;
|
|
165
|
+
/**
|
|
166
|
+
* Parts of the page that one place accounts for, which is the key the order is
|
|
167
|
+
* on.
|
|
168
|
+
*
|
|
169
|
+
* **Withheld on a page the order did not rank, and that is a claim rather than
|
|
170
|
+
* a default.** A `mismatched` page has places and a number for them, and the
|
|
171
|
+
* number is an artefact of the wrong pair; `0` would read as *nothing here
|
|
172
|
+
* went unread*, which is the opposite of what is known. The standing is where
|
|
173
|
+
* *there is no figure* is said.
|
|
174
|
+
*/
|
|
175
|
+
readonly costs: number | null;
|
|
176
|
+
/**
|
|
177
|
+
* What share of the page's parts that one place accounts for, or `null` on the
|
|
178
|
+
* same terms as {@link PageUnread.costs}.
|
|
179
|
+
*
|
|
180
|
+
* The tie-break and the sentence a small page needs: forty parts behind one
|
|
181
|
+
* band is most of a fifty-part page and a corner of a four-hundred-part one.
|
|
182
|
+
*/
|
|
183
|
+
readonly share: number | null;
|
|
184
|
+
};
|
|
185
|
+
/** One place the reading of a page stopped, with the page it is on. */
|
|
186
|
+
export type DeploymentPlace = {
|
|
187
|
+
readonly treeId: TreeId;
|
|
188
|
+
readonly revision: number;
|
|
189
|
+
readonly audienceId: AudienceId | null;
|
|
190
|
+
/** The place itself, carried whole off its page's reading. */
|
|
191
|
+
readonly at: UnreachedPart;
|
|
192
|
+
/** What share of that page's parts this one place accounts for. */
|
|
193
|
+
readonly share: number;
|
|
194
|
+
};
|
|
195
|
+
/** A deployment's pages, by what one fix to each would recover. */
|
|
196
|
+
export type DeploymentUnread = {
|
|
197
|
+
/**
|
|
198
|
+
* Every page with a place the reading stopped and a sound pair behind it,
|
|
199
|
+
* worst first.
|
|
200
|
+
*
|
|
201
|
+
* Most parts behind one place, then the larger share of the page, then by tree
|
|
202
|
+
* id and newest revision first — so two pages that cost the same do not
|
|
203
|
+
* reorder on a refresh.
|
|
204
|
+
*/
|
|
205
|
+
readonly ranked: readonly PageUnread[];
|
|
206
|
+
/** Every other page, by tree id and newest revision first. */
|
|
207
|
+
readonly unranked: readonly PageUnread[];
|
|
208
|
+
/** The head of the order, which is the one place in this deployment to go to first. */
|
|
209
|
+
readonly worst: PageUnread | null;
|
|
210
|
+
/** How many pages stand in each state, over the ranked and the unranked alike. */
|
|
211
|
+
readonly standings: Readonly<Record<UnreadStanding, number>>;
|
|
212
|
+
/**
|
|
213
|
+
* Distinct trees across every page read, which is not the number of pages.
|
|
214
|
+
*
|
|
215
|
+
* Two revisions of one tree are two live versions of one page and both stand,
|
|
216
|
+
* as they do in every order under this (0250, 0271).
|
|
217
|
+
*/
|
|
218
|
+
readonly trees: number;
|
|
219
|
+
/**
|
|
220
|
+
* Places the reading stopped, added across the **ranked** pages.
|
|
221
|
+
*
|
|
222
|
+
* The half of the headline that is the number of things to do. A `mismatched`
|
|
223
|
+
* page's places are not in it, because a figure taken off a wrong pair is not
|
|
224
|
+
* a thing to do — the row carries them, so nothing is lost by leaving them out
|
|
225
|
+
* of the sum (0301, 0326).
|
|
226
|
+
*/
|
|
227
|
+
readonly places: number;
|
|
228
|
+
/**
|
|
229
|
+
* Parts nobody reached, added across the **ranked** pages.
|
|
230
|
+
*
|
|
231
|
+
* The other half, and the figure a screen would otherwise have printed on its
|
|
232
|
+
* own: *four hundred and twelve unread parts* is true and is nine things to
|
|
233
|
+
* fix. Addable because a part is a node of one revision counted once — a
|
|
234
|
+
* weight over the pages the caller read, and not a deployment total.
|
|
235
|
+
*/
|
|
236
|
+
readonly unseen: number;
|
|
237
|
+
/**
|
|
238
|
+
* Pages whose reading names a part that said nothing while a part inside it
|
|
239
|
+
* reported reach — a **slice** of the rows and not a further list.
|
|
240
|
+
*
|
|
241
|
+
* A fix in the library rather than a page to rewrite: a reader was
|
|
242
|
+
* demonstrably below the part, so it was on screen and did not say so, which
|
|
243
|
+
* is a primitive not spreading its identity attributes. In the rows' own
|
|
244
|
+
* order, and every page here is in `ranked` or `unranked` as well and counted
|
|
245
|
+
* once in both this and {@link DeploymentUnread.standings}.
|
|
246
|
+
*/
|
|
247
|
+
readonly notReporting: readonly PageUnread[];
|
|
248
|
+
/**
|
|
249
|
+
* Readings of a revision beyond the first, which were dropped.
|
|
250
|
+
*
|
|
251
|
+
* A caller that concatenated two reads holds one page twice, and a page twice
|
|
252
|
+
* in an order is the one way an order lies about how much there is to fix.
|
|
253
|
+
* Dropped rather than added, because a count that has been added cannot be
|
|
254
|
+
* unadded (0158).
|
|
255
|
+
*/
|
|
256
|
+
readonly duplicated: number;
|
|
257
|
+
};
|
|
258
|
+
/**
|
|
259
|
+
* Read a deployment's pages as the places their readings stopped.
|
|
260
|
+
*
|
|
261
|
+
* ```ts
|
|
262
|
+
* const assembly = windowAssemblyOf(window, context)
|
|
263
|
+
* const unread = deploymentUnreadOf(assembly.readings.pages.map(pageFrontierOf))
|
|
264
|
+
* ```
|
|
265
|
+
*
|
|
266
|
+
* The frontiers are handed in rather than derived from a window here, for the
|
|
267
|
+
* reason every derived reading in this subsystem takes readings: each is
|
|
268
|
+
* separately useful and separately drawn, and deriving one twice is how two
|
|
269
|
+
* screens come to disagree about one page.
|
|
270
|
+
*
|
|
271
|
+
* @param pages One frontier per page the caller read. Two readings of one page
|
|
272
|
+
* are one page: they are keyed on a tree, a revision **and** an audience
|
|
273
|
+
* (`readingKeyOf`), the first of them stands, and the rest are counted in
|
|
274
|
+
* {@link DeploymentUnread.duplicated} rather than quietly doubling a figure.
|
|
275
|
+
*/
|
|
276
|
+
export declare const deploymentUnreadOf: (pages: readonly PageFrontier[]) => DeploymentUnread;
|
|
277
|
+
/**
|
|
278
|
+
* Every place the reading stopped across the deployment, worst first.
|
|
279
|
+
*
|
|
280
|
+
* The question the per-page reading could not be asked: *where in this
|
|
281
|
+
* deployment is the one place worth going to*, over nine pages rather than one.
|
|
282
|
+
* By what each place accounts for, then by the share of its own page, then by
|
|
283
|
+
* the page order and the page's own reading order — so a refresh does not
|
|
284
|
+
* reshuffle two places of one size.
|
|
285
|
+
*
|
|
286
|
+
* **Only the ranked pages.** A `mismatched` page's places are artefacts of a
|
|
287
|
+
* wrong tree-and-window pair, and this is the list whose rows are furthest from
|
|
288
|
+
* the standing that says so, so they are left out rather than drawn with a flag
|
|
289
|
+
* nobody reads. They are on the row, in `unranked`, where the order put them.
|
|
290
|
+
*/
|
|
291
|
+
export declare const worstPlacesIn: (unread: DeploymentUnread, limit?: number) => readonly DeploymentPlace[];
|
|
292
|
+
//# sourceMappingURL=unread.d.ts.map
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
import { everyMemberOf } from "../closed-set.js";
|
|
2
|
+
import { audienceScopeRead, readingKeyOf } from "./audiences.js";
|
|
3
|
+
import { largestUnreachedIn, } from "./frontier.js";
|
|
4
|
+
export const UNREAD_STANDINGS = everyMemberOf()([
|
|
5
|
+
"ranked",
|
|
6
|
+
"whole",
|
|
7
|
+
"unread",
|
|
8
|
+
"unsplit",
|
|
9
|
+
"mismatched",
|
|
10
|
+
]);
|
|
11
|
+
/** One line per standing, for a surface naming why a page is where it is. */
|
|
12
|
+
export const describeUnreadStanding = (standing) => {
|
|
13
|
+
switch (standing) {
|
|
14
|
+
case "ranked":
|
|
15
|
+
return "in the order, by the parts of the page its largest unread place accounts for";
|
|
16
|
+
case "whole":
|
|
17
|
+
return "every part of this page was reached by somebody";
|
|
18
|
+
case "unread":
|
|
19
|
+
return "nothing reported a view of this version in the window";
|
|
20
|
+
case "unsplit":
|
|
21
|
+
return "one window holds two forms of the page and says which readers neither";
|
|
22
|
+
case "mismatched":
|
|
23
|
+
return "its counters name nodes this version does not contain, so nothing here is evidence";
|
|
24
|
+
}
|
|
25
|
+
};
|
|
26
|
+
const EMPTY_STANDINGS = Object.freeze(Object.fromEntries(UNREAD_STANDINGS.map((standing) => [standing, 0])));
|
|
27
|
+
/** Tree id, then newest revision first, then form — the order every reading here publishes. */
|
|
28
|
+
const byPage = (one, other) => one.treeId.localeCompare(other.treeId) ||
|
|
29
|
+
other.revision - one.revision ||
|
|
30
|
+
(one.audienceId ?? "").localeCompare(other.audienceId ?? "");
|
|
31
|
+
/**
|
|
32
|
+
* What one reading's emptiness was, asked in the order the wrong answers are
|
|
33
|
+
* comforting in.
|
|
34
|
+
*
|
|
35
|
+
* `mismatched` first, because a wrong pair produces places and figures and they
|
|
36
|
+
* are the most plausible-looking output this reading has. Then `unsplit` before
|
|
37
|
+
* `unread`, because a window read as neither of two forms has a view floor of
|
|
38
|
+
* nought while its counters are full, so *nobody opened this page* is the
|
|
39
|
+
* comforting half of that pair too. Only then is an empty frontier allowed to
|
|
40
|
+
* mean what it looks like.
|
|
41
|
+
*/
|
|
42
|
+
const standingOf = (reading) => {
|
|
43
|
+
if (reading.orphaned > 0)
|
|
44
|
+
return "mismatched";
|
|
45
|
+
if (audienceScopeRead(reading).reading === "mixed")
|
|
46
|
+
return "unsplit";
|
|
47
|
+
if (reading.views === 0)
|
|
48
|
+
return "unread";
|
|
49
|
+
return reading.frontier.length > 0 ? "ranked" : "whole";
|
|
50
|
+
};
|
|
51
|
+
const rowOf = (reading) => {
|
|
52
|
+
const standing = standingOf(reading);
|
|
53
|
+
const at = standing === "ranked" ? (largestUnreachedIn(reading, 1)[0] ?? null) : null;
|
|
54
|
+
return {
|
|
55
|
+
treeId: reading.treeId,
|
|
56
|
+
revision: reading.revision,
|
|
57
|
+
audienceId: reading.audienceId,
|
|
58
|
+
standing,
|
|
59
|
+
reading,
|
|
60
|
+
at,
|
|
61
|
+
costs: at?.unseen ?? null,
|
|
62
|
+
share: at === null || reading.parts === 0 ? null : at.unseen / reading.parts,
|
|
63
|
+
};
|
|
64
|
+
};
|
|
65
|
+
/** Most parts behind one place, then the larger share, then the page order. */
|
|
66
|
+
const byCost = (one, other) => (other.costs ?? 0) - (one.costs ?? 0) ||
|
|
67
|
+
(other.share ?? 0) - (one.share ?? 0) ||
|
|
68
|
+
byPage(one, other);
|
|
69
|
+
/**
|
|
70
|
+
* Read a deployment's pages as the places their readings stopped.
|
|
71
|
+
*
|
|
72
|
+
* ```ts
|
|
73
|
+
* const assembly = windowAssemblyOf(window, context)
|
|
74
|
+
* const unread = deploymentUnreadOf(assembly.readings.pages.map(pageFrontierOf))
|
|
75
|
+
* ```
|
|
76
|
+
*
|
|
77
|
+
* The frontiers are handed in rather than derived from a window here, for the
|
|
78
|
+
* reason every derived reading in this subsystem takes readings: each is
|
|
79
|
+
* separately useful and separately drawn, and deriving one twice is how two
|
|
80
|
+
* screens come to disagree about one page.
|
|
81
|
+
*
|
|
82
|
+
* @param pages One frontier per page the caller read. Two readings of one page
|
|
83
|
+
* are one page: they are keyed on a tree, a revision **and** an audience
|
|
84
|
+
* (`readingKeyOf`), the first of them stands, and the rest are counted in
|
|
85
|
+
* {@link DeploymentUnread.duplicated} rather than quietly doubling a figure.
|
|
86
|
+
*/
|
|
87
|
+
export const deploymentUnreadOf = (pages) => {
|
|
88
|
+
const first = new Map();
|
|
89
|
+
let duplicated = 0;
|
|
90
|
+
for (const reading of pages) {
|
|
91
|
+
const key = readingKeyOf(reading);
|
|
92
|
+
if (first.has(key))
|
|
93
|
+
duplicated += 1;
|
|
94
|
+
else
|
|
95
|
+
first.set(key, rowOf(reading));
|
|
96
|
+
}
|
|
97
|
+
const rows = [...first.values()].sort(byPage);
|
|
98
|
+
const ranked = rows.filter((row) => row.standing === "ranked").sort(byCost);
|
|
99
|
+
const standings = rows.reduce((counted, row) => ({ ...counted, [row.standing]: counted[row.standing] + 1 }), { ...EMPTY_STANDINGS });
|
|
100
|
+
return {
|
|
101
|
+
ranked,
|
|
102
|
+
unranked: rows.filter((row) => row.standing !== "ranked"),
|
|
103
|
+
worst: ranked[0] ?? null,
|
|
104
|
+
standings,
|
|
105
|
+
trees: new Set(rows.map((row) => row.treeId)).size,
|
|
106
|
+
places: ranked.reduce((total, row) => total + row.reading.frontier.length, 0),
|
|
107
|
+
unseen: ranked.reduce((total, row) => total + row.reading.unseen, 0),
|
|
108
|
+
notReporting: rows.filter((row) => row.reading.notReporting.length > 0),
|
|
109
|
+
duplicated,
|
|
110
|
+
};
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* Every place the reading stopped across the deployment, worst first.
|
|
114
|
+
*
|
|
115
|
+
* The question the per-page reading could not be asked: *where in this
|
|
116
|
+
* deployment is the one place worth going to*, over nine pages rather than one.
|
|
117
|
+
* By what each place accounts for, then by the share of its own page, then by
|
|
118
|
+
* the page order and the page's own reading order — so a refresh does not
|
|
119
|
+
* reshuffle two places of one size.
|
|
120
|
+
*
|
|
121
|
+
* **Only the ranked pages.** A `mismatched` page's places are artefacts of a
|
|
122
|
+
* wrong tree-and-window pair, and this is the list whose rows are furthest from
|
|
123
|
+
* the standing that says so, so they are left out rather than drawn with a flag
|
|
124
|
+
* nobody reads. They are on the row, in `unranked`, where the order put them.
|
|
125
|
+
*/
|
|
126
|
+
export const worstPlacesIn = (unread, limit) => {
|
|
127
|
+
const places = unread.ranked.flatMap((row) => largestUnreachedIn(row.reading).map((at) => ({
|
|
128
|
+
treeId: row.treeId,
|
|
129
|
+
revision: row.revision,
|
|
130
|
+
audienceId: row.audienceId,
|
|
131
|
+
at,
|
|
132
|
+
share: row.reading.parts === 0 ? 0 : at.unseen / row.reading.parts,
|
|
133
|
+
})));
|
|
134
|
+
const ordered = places.sort((one, other) => other.at.unseen - one.at.unseen || other.share - one.share);
|
|
135
|
+
return limit === undefined ? ordered : ordered.slice(0, limit);
|
|
136
|
+
};
|
|
137
|
+
//# sourceMappingURL=unread.js.map
|