@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.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -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