@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
@@ -0,0 +1,271 @@
1
+ import type { NodeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import { type PrimitiveRole } from "../role.js";
4
+ import { type KindKey } from "./library.js";
5
+ import type { PageReading } from "./parts.js";
6
+ /**
7
+ * **Which of a deployment's components are silent.**
8
+ *
9
+ * [0382](../../decisions/0382-a-part-that-reported-nothing-with-a-reader-below-it-is-an-eighth-collection-fault-and-it-reaches-both-ranking-keys.md)
10
+ * named the defect: a part that reported nothing while a part **inside** it
11
+ * reported reach. A reader was demonstrably below it, so it was on a screen and
12
+ * did not say so — a primitive that does not spread the identity attributes a
13
+ * broadcaster reads, or a sender switched on halfway through a release. It is
14
+ * raised per page, as `parts-unreporting` on `PageHealth` ([`health.ts`](health.ts)), and it reaches
15
+ * both of the fix-list's ranking keys.
16
+ *
17
+ * **Per page is the wrong unit for it, and this is the right one.** A deployment
18
+ * with forty pages built out of one silent `loom.accordion` gets forty faulted
19
+ * pages, and nothing in the repository says they are forty symptoms of one
20
+ * thing. The fix is in the library — one primitive, once — and the errand the
21
+ * fix-list hands over is *rewrite these forty pages*. This gathers the same
22
+ * defect by {@link KindKey}, the way
23
+ * [`library.ts`](library.ts) gathers standing and
24
+ * [`library-reach.ts`](library-reach.ts) gathers readers, so the sentence is
25
+ * *`loom.accordion` is silent in thirty-one of the thirty-four places it stands,
26
+ * across nineteen of your pages*.
27
+ *
28
+ * It is the **twenty-fourth** reading taken out of the server-side join of 0212
29
+ * rather than collected: no payload field, no counter, no column, no table, no
30
+ * byte on any wire, and nothing in a reader's browser.
31
+ *
32
+ * ## The denominator is the placements the defect could be seen on
33
+ *
34
+ * This is the whole of the design and the only place it can go wrong.
35
+ *
36
+ * A silent **leaf** — a heading, a price, a control with nothing under it —
37
+ * produces exactly the rows a part nobody reached produces. There is no witness
38
+ * below it and there never can be, so the defect is undetectable there. A
39
+ * placement that holds parts but whose window reported no reach below it is
40
+ * undetectable **today**: nobody has been under it yet.
41
+ *
42
+ * So every placement is in exactly one of three states, and they add to
43
+ * {@link KindSenders.placements}:
44
+ *
45
+ * - {@link KindSenders.leaves} — holds nothing. Never checkable.
46
+ * - {@link KindSenders.unwitnessed} — holds parts, nothing below reported reach.
47
+ * Not checkable in this window.
48
+ * - {@link KindSenders.witnessed} — at least one part below reported reach. The
49
+ * population this reading is about.
50
+ *
51
+ * {@link KindSenders.share} is `silent ÷ witnessed` and never `silent ÷
52
+ * placements`. Dividing by the placements would make every library of mostly
53
+ * leaves look healthy and every quiet window look healthier still — a share that
54
+ * moves when readers arrive rather than when a sender is fixed, which is the
55
+ * direction 0212 says a census of a quiet deployment must never be wrong in.
56
+ *
57
+ * ## The share is a floor, and the bracket says by how much
58
+ *
59
+ * A witnessed placement whose own standing is `unknown` reported *something
60
+ * other than coming into view* with a reader below it — a press delegated to a
61
+ * band no `viewed` ever named. That is plausibly the same defect and 0382 does
62
+ * not claim it, because `unknown` is the absence of a claim (0282) and a fault
63
+ * raised on an absence would be the lie in the direction nobody checks.
64
+ *
65
+ * It is not dropped either. {@link KindSenders.indeterminate} counts those
66
+ * placements, {@link KindSenders.share} excludes them from the numerator and
67
+ * {@link KindSenders.atMost} includes them, so the true rate is bracketed rather
68
+ * than guessed. Where `indeterminate` is nought the two are equal and the
69
+ * bracket is a point, which is what a deployment with working senders publishes.
70
+ *
71
+ * ## It is the same defect the page reading raises, not a second one
72
+ *
73
+ * {@link KindSenders.silent} is counted on the rule `pageFrontierOf` is counted
74
+ * on — `skipped` with reach below it — spelled once in
75
+ * [`subtrees.ts`](subtrees.ts) and shared with it. The totals agree with the
76
+ * sum of `PageFrontier.notReporting` over the same readings term for term, which
77
+ * is asserted rather than described. Two numbers about one defect that could
78
+ * drift apart is the failure this subsystem already has several names for.
79
+ *
80
+ * ## One page counted twice is the one lie a census can tell
81
+ *
82
+ * A caller that concatenated two reads holds one revision twice. Readings are
83
+ * deduplicated on `readingKeyOf` and the drops are reported in
84
+ * {@link LibrarySenders.duplicated}
85
+ * ([0158](../../decisions/0158-counting-a-window-of-reader-signals-and-forgetting-it-are-one-operation.md)).
86
+ *
87
+ * Pure, and linear in the parts handed in: one pre-order pass and two prefix
88
+ * counts per reading, which is the bound rule 4 of
89
+ * [`docs/signals.md`](../../docs/signals.md) holds every reading here to.
90
+ */
91
+ /** Why a kind has no silent-sender share. */
92
+ export type SenderSilence =
93
+ /**
94
+ * Nothing in the pages read is of this kind at all.
95
+ *
96
+ * Only ever a role row, and the reason a role row exists for every member of
97
+ * the vocabulary: *nothing in this library is a landmark* is a fact about the
98
+ * library, and a surface that had to tell a missing row from an empty one
99
+ * would be reading the vocabulary itself. A type row cannot be in this state.
100
+ */
101
+ "unplaced"
102
+ /**
103
+ * Every placement of this kind holds nothing, so the defect cannot be seen on
104
+ * it at all.
105
+ *
106
+ * A structural answer and not a measurement one: no number of readers will
107
+ * ever put one below a leaf. A silent leaf and a leaf nobody reached report
108
+ * the same rows, and this reading does not guess between them.
109
+ */
110
+ | "unwitnessable"
111
+ /**
112
+ * It holds parts, and nothing below any of its placements reported reach in
113
+ * this window.
114
+ *
115
+ * A measurement answer: come back with readers. Kept apart from
116
+ * `unwitnessable` because the two are opposite instructions — one says there
117
+ * is nothing here that could ever be checked, the other says nobody has been
118
+ * under it yet.
119
+ */
120
+ | "unwitnessed";
121
+ export declare const SENDER_SILENCES: readonly SenderSilence[];
122
+ /** One line per silence, for a surface saying why a kind has no share. */
123
+ export declare const describeSenderSilence: (silence: SenderSilence) => string;
124
+ /** Whether one kind of part reports itself, everywhere it stands in the pages read. */
125
+ export type KindSenders = {
126
+ readonly kind: KindKey;
127
+ /** What part a type plays (0114), or `null`. Always `null` on a role row, which carries it as its key. */
128
+ readonly role: PrimitiveRole | null;
129
+ /** Element nodes of this kind across the readings. */
130
+ readonly placements: number;
131
+ /** Distinct trees it stands in, which is not the number of placements and not the number of readings. */
132
+ readonly trees: number;
133
+ /** Distinct revisions it stands in: two live revisions of one page are two. */
134
+ readonly revisions: number;
135
+ /** Placements holding no part at all, where the defect can never be seen. */
136
+ readonly leaves: number;
137
+ /** Placements holding parts, none of which reported reach in this window. */
138
+ readonly unwitnessed: number;
139
+ /**
140
+ * Placements with at least one part below them reporting reach — the
141
+ * population the rest of this row is about.
142
+ *
143
+ * `leaves + unwitnessed + witnessed` is {@link placements}.
144
+ */
145
+ readonly witnessed: number;
146
+ /**
147
+ * Witnessed placements that reported no view of themselves, which is the
148
+ * defect a page's own reading raises exactly as it raises it.
149
+ *
150
+ * A **floor** on what is wrong, and the reason is in the module
151
+ * documentation: a silent leaf is invisible to this reading and so is a
152
+ * silent part nobody has been under yet.
153
+ */
154
+ readonly silent: number;
155
+ /**
156
+ * Witnessed placements whose own standing is `unknown` — something other than
157
+ * a view, with a reader below.
158
+ *
159
+ * Plausibly the same defect, not claimed as it. The gap between
160
+ * {@link share} and {@link atMost}.
161
+ */
162
+ readonly indeterminate: number;
163
+ /**
164
+ * {@link silent} over {@link witnessed}; `null` where {@link silence} says why
165
+ * not.
166
+ *
167
+ * *Of the places this kind stands that could be checked, this share did not
168
+ * report themselves.*
169
+ */
170
+ readonly share: number | null;
171
+ /**
172
+ * `(silent + indeterminate) ÷ witnessed`, the other end of the bracket;
173
+ * `null` with {@link share}.
174
+ *
175
+ * Equal to {@link share} where nothing is indeterminate, which is what a
176
+ * deployment with working senders publishes.
177
+ */
178
+ readonly atMost: number | null;
179
+ /** Why {@link share} is not there, and `null` where it is. */
180
+ readonly silence: SenderSilence | null;
181
+ /**
182
+ * Distinct trees with at least one silent placement of this kind.
183
+ *
184
+ * The figure the per-page fault cannot give: *this one component is silent
185
+ * across nineteen of your pages*. Trees and not revisions, because a page is
186
+ * what an operator opens and two revisions of it are one errand.
187
+ */
188
+ readonly silentTrees: number;
189
+ /**
190
+ * Nodes of this kind that were silent, in the order the readings were handed
191
+ * in, capped at {@link SILENT_EXAMPLES}.
192
+ *
193
+ * Examples and never a list to act on: the errand is the primitive, and a
194
+ * surface that printed these as *the parts to fix* would be printing the
195
+ * wrong unit of work. Capped so that a library of forty pages cannot put
196
+ * tens of thousands of ids in a row nobody reads to the end.
197
+ */
198
+ readonly examples: readonly NodeId[];
199
+ };
200
+ /** How many silent nodes a row carries as examples. */
201
+ export declare const SILENT_EXAMPLES = 5;
202
+ /** Which of a deployment's kinds of part report themselves, and which are silent. */
203
+ export type LibrarySenders = {
204
+ /**
205
+ * Every type that stands anywhere, most silent placements first.
206
+ *
207
+ * Then the higher share, then by type, so two kinds silent in equally many
208
+ * places do not reorder on a refresh.
209
+ */
210
+ readonly byType: readonly KindSenders[];
211
+ /**
212
+ * Every role in the vocabulary that stands anywhere, then the row for parts
213
+ * whose type declared none, in the same order as {@link byType}.
214
+ */
215
+ readonly byRole: readonly KindSenders[];
216
+ /** Readings counted, which is revisions of pages and not trees. */
217
+ readonly pages: number;
218
+ /** Distinct trees across them. */
219
+ readonly trees: number;
220
+ /** Element nodes across them, which is the sum of every type row's placements. */
221
+ readonly placements: number;
222
+ /** Placements the defect could be seen on, over the whole library. */
223
+ readonly witnessed: number;
224
+ /**
225
+ * Silent placements over the whole library, which is the sum of
226
+ * `PageFrontier.notReporting` over the same readings.
227
+ */
228
+ readonly silent: number;
229
+ /** Witnessed placements whose own standing is `unknown`, over the whole library. */
230
+ readonly indeterminate: number;
231
+ /**
232
+ * The type silent in the most places, which is the component to fix first.
233
+ *
234
+ * By the **count** of places and not by the share, for the reason a page's
235
+ * falls are ranked by the readers they lose (0221) and a library by the places
236
+ * it is skipped in (0257): a kind silent in its one and only place is a
237
+ * perfect share and a smaller problem than one silent in thirty-one of
238
+ * thirty-four. `null` where nothing anywhere was silent — a deployment whose
239
+ * senders work and one nothing could check both, which {@link witnessed} tells
240
+ * apart.
241
+ *
242
+ * A type and never a role, because a type is the thing an author can replace.
243
+ */
244
+ readonly worstSender: KindSenders | null;
245
+ /**
246
+ * Readings of a revision beyond the first, which were dropped.
247
+ *
248
+ * A page twice in a census is the one way a census can lie about how much of
249
+ * a library there is (0158).
250
+ */
251
+ readonly duplicated: number;
252
+ /**
253
+ * Types whose readings disagreed about the role they play, where the first
254
+ * reading's answer stands.
255
+ *
256
+ * Two registries read as one library, which makes every role row below about
257
+ * neither (0114).
258
+ */
259
+ readonly roleDisagreed: readonly PrimitiveType[];
260
+ };
261
+ /**
262
+ * Which of a deployment's kinds of part report themselves.
263
+ *
264
+ * Takes the readings rather than the frontiers, for the reason every library
265
+ * reading does: a frontier names the silent nodes and nothing says what kind
266
+ * each one is, and the three states a placement can be in are a fact about the
267
+ * tree rather than about the stops. A caller with a window of counters reads
268
+ * each page, then this.
269
+ */
270
+ export declare const librarySendersOf: (readings: readonly PageReading[]) => LibrarySenders;
271
+ //# sourceMappingURL=library-senders.d.ts.map
@@ -0,0 +1,180 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { PRIMITIVE_ROLES } from "../role.js";
3
+ import { readingKeyOf } from "./audiences.js";
4
+ import { kindKeyOf } from "./library.js";
5
+ import { senderStatesOf, witnessedState } from "./subtrees.js";
6
+ export const SENDER_SILENCES = everyMemberOf()([
7
+ "unplaced",
8
+ "unwitnessable",
9
+ "unwitnessed",
10
+ ]);
11
+ /** One line per silence, for a surface saying why a kind has no share. */
12
+ export const describeSenderSilence = (silence) => {
13
+ switch (silence) {
14
+ case "unplaced":
15
+ return "nothing in the pages read is of this kind";
16
+ case "unwitnessable":
17
+ return "every place this kind stands holds nothing, so a silent sender could not be seen there";
18
+ case "unwitnessed":
19
+ return "nothing reported reach inside any place this kind stands, so nothing could witness it";
20
+ }
21
+ };
22
+ /** How many silent nodes a row carries as examples. */
23
+ export const SILENT_EXAMPLES = 5;
24
+ const tallying = (kind) => ({
25
+ kind,
26
+ role: null,
27
+ placements: 0,
28
+ trees: new Set(),
29
+ revisions: new Set(),
30
+ silentIn: new Set(),
31
+ leaves: 0,
32
+ unwitnessed: 0,
33
+ witnessed: 0,
34
+ silent: 0,
35
+ indeterminate: 0,
36
+ examples: [],
37
+ });
38
+ const add = (into, at, revision) => {
39
+ into.placements += 1;
40
+ into.trees.add(at.treeId);
41
+ into.revisions.add(revision);
42
+ if (at.state === "leaf")
43
+ into.leaves += 1;
44
+ else if (at.state === "unwitnessed")
45
+ into.unwitnessed += 1;
46
+ else
47
+ into.witnessed += 1;
48
+ if (at.state === "indeterminate")
49
+ into.indeterminate += 1;
50
+ if (at.state === "silent") {
51
+ into.silent += 1;
52
+ into.silentIn.add(at.treeId);
53
+ if (into.examples.length < SILENT_EXAMPLES)
54
+ into.examples.push(at.nodeId);
55
+ }
56
+ };
57
+ /**
58
+ * The silence, with the three reasons tried in the order they have to be tried
59
+ * in.
60
+ *
61
+ * Nothing of the kind first, because *there is no such part in this library* is
62
+ * a better answer than anything about readers and is true of the others by
63
+ * accident. Then the structural reason before the measurement one: *this can
64
+ * never be checked here* and *nobody has been under it yet* are opposite
65
+ * instructions, and a kind standing only in leaves is in the first however many
66
+ * readers arrive.
67
+ */
68
+ const silenceOf = (of) => {
69
+ if (of.placements === 0)
70
+ return "unplaced";
71
+ if (of.witnessed > 0)
72
+ return null;
73
+ return of.unwitnessed === 0 ? "unwitnessable" : "unwitnessed";
74
+ };
75
+ const rowOf = (of) => {
76
+ const silence = silenceOf(of);
77
+ return {
78
+ kind: of.kind,
79
+ role: of.kind.by === "type" ? of.role : null,
80
+ placements: of.placements,
81
+ trees: of.trees.size,
82
+ revisions: of.revisions.size,
83
+ leaves: of.leaves,
84
+ unwitnessed: of.unwitnessed,
85
+ witnessed: of.witnessed,
86
+ silent: of.silent,
87
+ indeterminate: of.indeterminate,
88
+ share: of.witnessed === 0 ? null : of.silent / of.witnessed,
89
+ atMost: of.witnessed === 0 ? null : (of.silent + of.indeterminate) / of.witnessed,
90
+ silence,
91
+ silentTrees: of.silentIn.size,
92
+ examples: [...of.examples],
93
+ };
94
+ };
95
+ /** The name a row is ordered by, which is the key's own and never the row's position. */
96
+ const nameOf = (kind) => (kind.by === "type" ? kind.type : (kind.role ?? ""));
97
+ /**
98
+ * The kind to look at first, which is the ranking rule spelled once.
99
+ *
100
+ * Most places silent, then the higher share, then by name — so a kind with no
101
+ * share at all sorts after one with a share of nought rather than above it,
102
+ * because `null` is *nothing could be checked* and not *every sender works*.
103
+ */
104
+ const worseOf = (one, other) => other.silent - one.silent ||
105
+ (other.share ?? -1) - (one.share ?? -1) ||
106
+ nameOf(one.kind).localeCompare(nameOf(other.kind));
107
+ /**
108
+ * Which of a deployment's kinds of part report themselves.
109
+ *
110
+ * Takes the readings rather than the frontiers, for the reason every library
111
+ * reading does: a frontier names the silent nodes and nothing says what kind
112
+ * each one is, and the three states a placement can be in are a fact about the
113
+ * tree rather than about the stops. A caller with a window of counters reads
114
+ * each page, then this.
115
+ */
116
+ export const librarySendersOf = (readings) => {
117
+ const rows = new Map();
118
+ const seen = new Set();
119
+ const trees = new Set();
120
+ const disagreed = new Set();
121
+ let pages = 0;
122
+ let duplicated = 0;
123
+ let placements = 0;
124
+ let witnessed = 0;
125
+ let silent = 0;
126
+ let indeterminate = 0;
127
+ for (const role of [...PRIMITIVE_ROLES, null]) {
128
+ const kind = { by: "role", role };
129
+ rows.set(kindKeyOf(kind), tallying(kind));
130
+ }
131
+ for (const reading of readings) {
132
+ const revision = readingKeyOf(reading);
133
+ if (seen.has(revision)) {
134
+ duplicated += 1;
135
+ continue;
136
+ }
137
+ seen.add(revision);
138
+ trees.add(reading.treeId);
139
+ pages += 1;
140
+ for (const { part, state } of senderStatesOf(reading.parts)) {
141
+ const placement = { nodeId: part.nodeId, treeId: reading.treeId, state };
142
+ placements += 1;
143
+ witnessed += witnessedState(state) ? 1 : 0;
144
+ silent += state === "silent" ? 1 : 0;
145
+ indeterminate += state === "indeterminate" ? 1 : 0;
146
+ const keys = [
147
+ { by: "type", type: part.type },
148
+ { by: "role", role: part.role },
149
+ ];
150
+ for (const kind of keys) {
151
+ const key = kindKeyOf(kind);
152
+ const row = rows.get(key) ?? tallying(kind);
153
+ if (kind.by === "type") {
154
+ if (row.placements === 0)
155
+ row.role = part.role;
156
+ else if (row.role !== part.role)
157
+ disagreed.add(part.type);
158
+ }
159
+ add(row, placement, revision);
160
+ rows.set(key, row);
161
+ }
162
+ }
163
+ }
164
+ const built = [...rows.values()].map(rowOf);
165
+ const byType = built.filter((row) => row.kind.by === "type").sort(worseOf);
166
+ return {
167
+ byType,
168
+ byRole: built.filter((row) => row.kind.by === "role").sort(worseOf),
169
+ pages,
170
+ trees: trees.size,
171
+ placements,
172
+ witnessed,
173
+ silent,
174
+ indeterminate,
175
+ worstSender: byType.find((row) => row.silent > 0) ?? null,
176
+ duplicated,
177
+ roleDisagreed: [...disagreed].sort((one, other) => one.localeCompare(other)),
178
+ };
179
+ };
180
+ //# sourceMappingURL=library-senders.js.map
@@ -4,7 +4,7 @@ import { inFormOrder } from "./audiences.js";
4
4
  import { copyChangeOf, spokenForOnBothSides } from "./copy-change.js";
5
5
  import { kindKeyOf } from "./library.js";
6
6
  import { partsByNodeIn } from "./library-change.js";
7
- import { readerShareCauseOf, librarySideOf, weightMovedOver, } from "./library-reach-change.js";
7
+ import { inUnscaledSideOrder, readerShareCauseOf, librarySideOf, weightMovedOver, } from "./library-reach-change.js";
8
8
  export const KIND_WORD_REACH_CHANGE_SILENCES = everyMemberOf()([
9
9
  "unplaced",
10
10
  "unpaired",
@@ -241,10 +241,6 @@ const worseOf = (one, other) => (one.words.wordsMoved ?? Number.POSITIVE_INFINIT
241
241
  (one.words.typicalNow ?? Number.POSITIVE_INFINITY) -
242
242
  (other.words.typicalNow ?? Number.POSITIVE_INFINITY) ||
243
243
  nameOf(one.kind).localeCompare(nameOf(other.kind));
244
- /** Tree id, then newest revision first, which is the order the page-view rows are read in. */
245
- const bySide = (one, other) => one.treeId.localeCompare(other.treeId) ||
246
- other.revision - one.revision ||
247
- one.side.localeCompare(other.side);
248
244
  /**
249
245
  * One carried passage's words, filed under what can be said about them.
250
246
  *
@@ -553,7 +549,7 @@ export const libraryWordReachChangeOf = (was, now) => {
553
549
  arrivalsWas,
554
550
  arrivalsNow,
555
551
  scaled,
556
- unscaled: [...unscaled].sort(bySide),
552
+ unscaled: [...unscaled].sort(inUnscaledSideOrder),
557
553
  mostAbandoned: byType.find((row) => (row.words.wordsMoved ?? 0) < 0) ?? null,
558
554
  mostTakenUp: byType
559
555
  .filter((row) => (row.words.wordsMoved ?? 0) > 0)
@@ -3,7 +3,9 @@ import { cursorPosition, pageEnds } from "../paging.js";
3
3
  import { ok } from "../result.js";
4
4
  import { systemClock } from "../runtime/events.js";
5
5
  import { clampReaderSignalLimit, } from "./journal.js";
6
- import { funnelKey, inAudience, pageViewKey, regionKey, tallyKey } from "./counters.js";
6
+ import { actedKey, arrivalKey, funnelHourKey, funnelKey, inAudience, pageViewKey, regionKey, tallyKey, } from "./counters.js";
7
+ import { arrivalHoursOf } from "./arrivals.js";
8
+ import { funnelPairKey } from "./funnel.js";
7
9
  /**
8
10
  * The buffer and the counters, in the process.
9
11
  *
@@ -16,6 +18,13 @@ import { funnelKey, inAudience, pageViewKey, regionKey, tallyKey } from "./count
16
18
  * against real time.
17
19
  */
18
20
  export const memoryReaderSignalJournal = (clock = systemClock) => {
21
+ /**
22
+ * Mutable rows rather than a frozen list, because one field on a stored
23
+ * delivery changes after it is written: the fold's instant (0351). The array
24
+ * is still replaced wholesale on a delete, so the only in-place write in this
25
+ * store is the stamp — which is the same single-column `UPDATE` Postgres
26
+ * makes.
27
+ */
19
28
  let batches = [];
20
29
  let nextSeq = 1;
21
30
  /**
@@ -44,6 +53,9 @@ export const memoryReaderSignalJournal = (clock = systemClock) => {
44
53
  const from = cursorPosition(request?.cursor);
45
54
  const direction = request?.direction ?? "newer";
46
55
  const matching = batches.filter((batch) => (request?.treeId === undefined || batch.treeId === request.treeId) &&
56
+ (request?.counted === undefined ||
57
+ request.counted === (batch.foldedAt !== undefined)) &&
58
+ (request?.view === undefined || batch.view === request.view) &&
47
59
  (from === undefined || (direction === "older" ? batch.seq < from : batch.seq > from)));
48
60
  /** A slice rather than a reverse: a page's order never depends on which end it came from. */
49
61
  const page = direction === "older" ? matching.slice(-limit) : matching.slice(0, limit);
@@ -55,6 +67,25 @@ export const memoryReaderSignalJournal = (clock = systemClock) => {
55
67
  }),
56
68
  }));
57
69
  },
70
+ /**
71
+ * Stamp the fold's instant on an unstamped prefix (0351).
72
+ *
73
+ * `foldedAt !== undefined` is the guard rather than a position comparison,
74
+ * so the second call over one prefix moves nothing — the property Postgres
75
+ * gets from `folded_at IS NULL` in its `WHERE`, written here so the two
76
+ * implementations are the same operation rather than two that happen to
77
+ * agree on the first call.
78
+ */
79
+ counted: ({ before, at }) => {
80
+ let counted = 0;
81
+ batches = batches.map((batch) => {
82
+ if (batch.seq >= before || batch.foldedAt !== undefined)
83
+ return batch;
84
+ counted += 1;
85
+ return { ...batch, foldedAt: at };
86
+ });
87
+ return Promise.resolve(ok({ counted }));
88
+ },
58
89
  /** `nextSeq` is not rewound, so a cursor held across a prune never resumes inside what it has seen. */
59
90
  forget: ({ before }) => {
60
91
  const kept = batches.filter((batch) => batch.seq >= before);
@@ -71,6 +102,9 @@ export const memoryReaderTallyStore = () => {
71
102
  const tallies = new Map();
72
103
  const funnels = new Map();
73
104
  const pageViews = new Map();
105
+ const arrivals = new Map();
106
+ const acted = new Map();
107
+ const funnelHours = new Map();
74
108
  /**
75
109
  * One row written from two sides, so the add is spelled once and told which
76
110
  * column it is moving.
@@ -118,6 +152,38 @@ export const memoryReaderTallyStore = () => {
118
152
  updatedAt: at,
119
153
  });
120
154
  };
155
+ /**
156
+ * One part's hour, added — the hourly slice of the four occurrence counters
157
+ * above (`acted.ts`).
158
+ */
159
+ const addActed = (count, at, audience) => {
160
+ const key = inAudience(audience, actedKey(count));
161
+ const existing = acted.get(key);
162
+ acted.set(key, {
163
+ ...count,
164
+ audienceId: audience,
165
+ activations: (existing?.activations ?? 0) + count.activations,
166
+ opens: (existing?.opens ?? 0) + count.opens,
167
+ closes: (existing?.closes ?? 0) + count.closes,
168
+ completions: (existing?.completions ?? 0) + count.completions,
169
+ updatedAt: at,
170
+ });
171
+ };
172
+ /**
173
+ * One pair's hour, added — the hourly cut of the two counts on the answer
174
+ * below (`funnel-hours.ts`).
175
+ */
176
+ const addFunnelHour = (count, at, audience) => {
177
+ const key = inAudience(audience, funnelHourKey(count));
178
+ const existing = funnelHours.get(key);
179
+ funnelHours.set(key, {
180
+ ...count,
181
+ audienceId: audience,
182
+ reached: (existing?.reached ?? 0) + count.reached,
183
+ converted: (existing?.converted ?? 0) + count.converted,
184
+ updatedAt: at,
185
+ });
186
+ };
121
187
  const addFunnel = (answer, at, audience) => {
122
188
  const key = inAudience(audience, funnelKey(answer));
123
189
  const existing = funnels.get(key);
@@ -143,8 +209,12 @@ export const memoryReaderTallyStore = () => {
143
209
  const audience = counters.audience ?? DEFAULT_AUDIENCE_ID;
144
210
  for (const tally of counters.tallies)
145
211
  addTally(tally, at, audience);
212
+ for (const count of counters.acted ?? [])
213
+ addActed(count, at, audience);
146
214
  for (const answer of counters.funnels)
147
215
  addFunnel(answer, at, audience);
216
+ for (const count of counters.funnelHours ?? [])
217
+ addFunnelHour(count, at, audience);
148
218
  addPageViews(counters.appearances ?? [], "appearances", at, audience);
149
219
  }
150
220
  return Promise.resolve(ok(undefined));
@@ -152,13 +222,84 @@ export const memoryReaderTallyStore = () => {
152
222
  return {
153
223
  applyWindow,
154
224
  apply: (counters, at, audience = DEFAULT_AUDIENCE_ID) => applyWindow([{ ...counters, audience }], at),
225
+ /**
226
+ * The total and the hour, or neither (`arrivals.ts`).
227
+ *
228
+ * Nothing here can fail once the hour is in hand, so the atomicity the
229
+ * interface promises costs this store nothing — which is exactly why the
230
+ * instant is turned into an hour **first**: the one failure the pair has is
231
+ * an instant that is not one, and a reference implementation that wrote the
232
+ * total and then discovered it would be a reference for the wrong thing.
233
+ */
155
234
  opened: (openings, at, audience = DEFAULT_AUDIENCE_ID) => {
235
+ const hours = arrivalHoursOf(openings, at);
236
+ if (!hours.ok)
237
+ return Promise.resolve(hours);
156
238
  addPageViews(openings, "opened", at, audience);
239
+ for (const count of hours.value) {
240
+ const key = inAudience(audience, arrivalKey(count));
241
+ const existing = arrivals.get(key);
242
+ arrivals.set(key, {
243
+ ...count,
244
+ audienceId: audience,
245
+ views: (existing?.views ?? 0) + count.views,
246
+ updatedAt: at,
247
+ });
248
+ }
157
249
  return Promise.resolve(ok(undefined));
158
250
  },
159
251
  tallies: (request) => Promise.resolve(ok([...tallies.values()].filter((row) => matches(row, request)))),
160
252
  funnels: (request) => Promise.resolve(ok([...funnels.values()].filter((row) => matches(row, request)))),
161
253
  pageViews: (request) => Promise.resolve(ok([...pageViews.values()].filter((row) => matches(row, request)))),
254
+ /**
255
+ * The rows in the range, and the first hour the scope has at all.
256
+ *
257
+ * The second figure is taken over the same narrowing without the range,
258
+ * which is the half a caller cannot compute from the first: a range that
259
+ * came back empty is *nobody arrived* or *we were not counting*, and the
260
+ * only way to tell is to look outside the range.
261
+ */
262
+ arrivals: (request) => {
263
+ const scoped = [...arrivals.values()].filter((row) => matches(row, request));
264
+ const hours = scoped.filter((row) => (request?.from === undefined || row.hour >= request.from) &&
265
+ (request?.to === undefined || row.hour < request.to));
266
+ const begins = scoped.reduce((first, row) => (first === undefined || row.hour < first ? row.hour : first), undefined);
267
+ return Promise.resolve(ok({ hours, ...(begins === undefined ? {} : { begins }) }));
268
+ },
269
+ /**
270
+ * The same two answers as `arrivals`, narrowed to a part as well.
271
+ *
272
+ * The part narrows **both** halves: the first hour a goal was ever counted
273
+ * in is the first hour that part was acted in, not the first hour the
274
+ * deployment counted anything — otherwise a goal made today would report
275
+ * that it has been measured since the deployment started and draw a flat
276
+ * nought back to then.
277
+ */
278
+ acted: (request) => {
279
+ const scoped = [...acted.values()].filter((row) => matches(row, request) &&
280
+ (request?.nodeId === undefined || row.nodeId === request.nodeId));
281
+ const hours = scoped.filter((row) => (request?.from === undefined || row.hour >= request.from) &&
282
+ (request?.to === undefined || row.hour < request.to));
283
+ const begins = scoped.reduce((first, row) => (first === undefined || row.hour < first ? row.hour : first), undefined);
284
+ return Promise.resolve(ok({ hours, ...(begins === undefined ? {} : { begins }) }));
285
+ },
286
+ /**
287
+ * The same two answers, narrowed to one funnel as well.
288
+ *
289
+ * The pair narrows **both** halves, for the reason the part narrows both of
290
+ * `acted`'s: a step set this afternoon must report that it has been
291
+ * measurable since this afternoon, not since the deployment's first reader.
292
+ * The ends are compared by `funnelPairKey`, which is the one rule for what
293
+ * makes two funnel rows the same question.
294
+ */
295
+ funnelHours: (request) => {
296
+ const asked = request?.pair === undefined ? undefined : funnelPairKey(request.pair);
297
+ const scoped = [...funnelHours.values()].filter((row) => matches(row, request) && (asked === undefined || funnelPairKey(row.pair) === asked));
298
+ const hours = scoped.filter((row) => (request?.from === undefined || row.hour >= request.from) &&
299
+ (request?.to === undefined || row.hour < request.to));
300
+ const begins = scoped.reduce((first, row) => (first === undefined || row.hour < first ? row.hour : first), undefined);
301
+ return Promise.resolve(ok({ hours, ...(begins === undefined ? {} : { begins }) }));
302
+ },
162
303
  };
163
304
  };
164
305
  /**