@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,276 @@
1
+ import { type DeploymentAgenda } from "./agenda.js";
2
+ import { type ArrivalStanding, type TurnedAwayTally } from "./arriving.js";
3
+ import { type DeploymentConversion } from "./conversion.js";
4
+ import { type DeploymentReading } from "./deployment.js";
5
+ import { type CollectionHealth, type CollectionSchedule } from "./health.js";
6
+ import { type ReadingProgress } from "./progress.js";
7
+ import { type DeploymentUnread } from "./unread.js";
8
+ import type { WindowFunnels } from "./window-funnels.js";
9
+ import type { ReaderWindow, WindowAssembly } from "./window.js";
10
+ /**
11
+ * The deployment's fix-list, off one window, in one call.
12
+ *
13
+ * `deploymentAgendaOf` answers *what should this deployment do next* — one line
14
+ * saying *rewrite this page*, *rewrite this ask* or *repair this measurement*,
15
+ * with the page named
16
+ * ([0330](../../decisions/0330-the-page-to-fix-first-is-not-the-page-to-fix-when-its-own-fault-made-the-fall.md),
17
+ * [0336](../../decisions/0336-a-fault-reaches-a-conversion-and-a-fall-differently-so-the-fix-list-asks-each-order-its-own-question.md)).
18
+ * It is the reading a deployment's screen opens with, and it is the furthest
19
+ * thing in this subsystem from a store: three readings, over two row sets, with
20
+ * a per-page reading derived under one of them.
21
+ *
22
+ * 0330 rejected deriving its inputs inside it, and that still holds — each of
23
+ * the three is separately useful and separately drawn, and deriving any of them
24
+ * twice is how two screens come to disagree about one deployment. What it also
25
+ * said, in rejecting a home for the composition, was that *both of its inputs
26
+ * are one call with one argument, so there is nothing here a caller can get
27
+ * wrong.* **That was true of two inputs and is not true of three.** This is the
28
+ * line it was said about, as a caller has to write it today:
29
+ *
30
+ * ```ts
31
+ * const agenda = deploymentAgendaOf(
32
+ * deploymentReadingOf(assembly.readings.pages.map(readingProgressOf), window.pageViews),
33
+ * deploymentConversionOf(windowFunnelsOf(window, assembly).pages),
34
+ * collectionHealthOf(assembly.readings.pages, window.pageViews),
35
+ * …
36
+ * )
37
+ * ```
38
+ *
39
+ * ## The three things a caller writing that line gets wrong
40
+ *
41
+ * **The schedule is the one that fails silently and in the unsafe direction.**
42
+ * The third argument to `collectionHealthOf` is optional, because a caller with
43
+ * no schedule to state should get a reading that judges nothing rather than one
44
+ * that judges against a default. The line above leaves it out — and what that
45
+ * costs is not a missing row.
46
+ *
47
+ * `collection-stalled` is never raised, so a deployment whose folds have stopped
48
+ * reads **sound**; and because a stalled fold reaches both ranking keys, the
49
+ * fall and the leak it manufactured are never withdrawn either. The two readings
50
+ * of one window differ by one fault and say the opposite thing about the same
51
+ * page: *rewrite this page* where no schedule was stated, *repair this
52
+ * measurement* where one was. An operator sent to rewrite a page whose numbers
53
+ * are an artefact of its own stalled collection is the exact failure the
54
+ * fix-list was built to prevent
55
+ * ([0330](../../decisions/0330-the-page-to-fix-first-is-not-the-page-to-fix-when-its-own-fault-made-the-fall.md)),
56
+ * arriving through the one argument nothing asked for.
57
+ *
58
+ * So here it is required and may be `null`: *this deployment states no schedule*
59
+ * is a word a reviewer can read rather than a space where an argument is not.
60
+ * That is the shape the region floor was given, for the same reason
61
+ * ([0322](../../decisions/0322-a-window-is-read-off-one-deployment-context-and-the-region-floor-is-not-optional.md)).
62
+ *
63
+ * **The progress readings are over the window's readings and not over a
64
+ * library.** The nearest line to hand maps `libraries.now.readings`, which
65
+ * type-checks, runs, and drops the earlier revision of every page revised inside
66
+ * the window and every form the placings could not place — so the fix-list is an
67
+ * order over some of the deployment's pages with nothing saying which
68
+ * ([0327](../../decisions/0327-the-figures-a-window-holds-about-itself-are-a-second-rung-and-a-region-row-set-is-deduplicated-once.md)).
69
+ *
70
+ * **All three readings have to be of one window.** `DeploymentAgenda.unpaired`
71
+ * exists because they need not be: a caller holding an order of one window and a
72
+ * health reading of another gets a join of the intersection and a count of what
73
+ * fell out of it. From here the three are over one assembly's one set of
74
+ * readings, so all three counts are **nought by construction** and the fix-list
75
+ * is of every page the window holds.
76
+ *
77
+ * **Nothing told a caller that an empty fix-list is three deployments.** The
78
+ * join publishes `subject` for that
79
+ * ([0326](../../decisions/0326-a-quiet-window-and-a-refusing-door-are-two-states-and-a-refusal-names-no-page.md)),
80
+ * and it needs an arrival standing to say which — which a caller of this rung
81
+ * could not compute before calling it, because the health reading the standing
82
+ * is taken over is made *inside* here. So the line above reads `unverified`
83
+ * about a deployment whose door is refusing every delivery: the one state the
84
+ * arrival reading exists for, and the one the fix-list was told nothing about.
85
+ *
86
+ * ## Why this rung takes the refusal rows and not the reading over them
87
+ *
88
+ * The 31 October finding about `arrivalStandingOf` asked that a rung **take the
89
+ * reading's result** rather than compute it, and
90
+ * [0327](../../decisions/0327-the-figures-a-window-holds-about-itself-are-a-second-rung-and-a-region-row-set-is-deduplicated-once.md)
91
+ * upheld it for the figures rung. The reason was the scope: a refusal counter is
92
+ * the deployment's own table, keyed by application and reason, written on the
93
+ * request path and holding nothing a window holds (0309), so an assembly that
94
+ * went looking for it would be reaching a second store on a second scope.
95
+ *
96
+ * That reason is about **reaching a store**, and this does not: the rows are
97
+ * handed in, exactly as the window's rows are. What this rung has that the
98
+ * figures rung did not is the other half of the reading — `arrivalStandingOf`
99
+ * is taken over a health reading, and this is the one place in the subsystem
100
+ * where that reading is made. A caller asked for the *result* here would have
101
+ * to compute the health reading itself to get one, which is the second copy of
102
+ * a reading this rung exists to prevent.
103
+ *
104
+ * So the rows come in and the reading is made once, over the health reading the
105
+ * rows below were judged by — which is also the only way the subject can be a
106
+ * claim about *these* rows.
107
+ *
108
+ * ## Why the funnels are taken and the other two are made
109
+ *
110
+ * The rule is the one the rungs under this already keep, stated so the next
111
+ * reading added here does not have to re-derive it: **a reading with a published
112
+ * call of its own is handed in; a reading that is one call over the assembly's
113
+ * own readings is made.**
114
+ *
115
+ * `windowFunnelsOf` is that published call
116
+ * ([0333](../../decisions/0333-a-deployments-conversions-are-a-third-order-ranked-on-the-loss-between-the-two-ends.md)),
117
+ * and its whole point is that every side of every funnel comparison is the same
118
+ * object as the reading of that form — so reading the funnels again here would
119
+ * put two answers of one revision on one screen, which is the thing that call
120
+ * exists to make impossible. The order of falls and the health reading have no
121
+ * such call, and both are made here and published whole.
122
+ *
123
+ * ## Why the order of places is published and does not reach the fix-list
124
+ *
125
+ * `deploymentUnreadOf` is the fourth order over the same pages
126
+ * ([0377](../../decisions/0377-a-deployments-unread-places-are-a-fourth-order-ranked-on-what-one-fix-recovers.md)),
127
+ * and it is **made** here under the rule above: `pageFrontierOf` is one call
128
+ * over the assembly's own readings, so a caller asked to hand it in would be
129
+ * writing the line this rung exists to write.
130
+ *
131
+ * It is not an argument to `deploymentAgendaOf` and does not move
132
+ * `DeploymentAgenda.first`. Its key is parts of a page and the fix-list's three
133
+ * are readers, so there is no comparing them (0327) — and re-ranking what an
134
+ * operator is already handed, on a figure in a fourth unit, is a judgement about
135
+ * a screen rather than a join. The two stand side by side here, which is the
136
+ * shape that lets a surface choose and lets neither hide the other.
137
+ *
138
+ * Every page's frontier is reachable from it — each row carries the reading
139
+ * whole — so there is no second list of them beside this, for the reason there
140
+ * is no second anything in this rung.
141
+ *
142
+ * ## It composes and does not count
143
+ *
144
+ * Nothing here counts, divides, sums or withholds — the rule the rungs under it
145
+ * keep. It decides which rows each of four published readings is entitled to and
146
+ * calls them. In particular there is no total over what the four left out: an
147
+ * unranked page, a page with no question, a faultless page and a page the door
148
+ * cannot scale are four different absences, and a sum over them would be a
149
+ * figure in none.
150
+ *
151
+ * Linear in the window, being one pass of each reading over the same readings.
152
+ */
153
+ /** A deployment's fix-list and each of the readings it was joined from. */
154
+ export type WindowAgenda<TReason extends string = string> = {
155
+ /**
156
+ * Where reading stops on each page the window holds, in the readings' own
157
+ * order.
158
+ *
159
+ * Published because it is drawn: a screen that names the page to fix next
160
+ * shows the run of parts the fall is in, and these are the readings the order
161
+ * below was ranked from rather than a second set of them.
162
+ */
163
+ readonly progress: readonly ReadingProgress[];
164
+ /**
165
+ * The pages by the readers each loses at its sharpest fall, worst first.
166
+ *
167
+ * `duplicated` and `duplicatedRows` are nought from here: the assembly never
168
+ * holds two readings of one page, and the window's door rows are its own set.
169
+ */
170
+ readonly order: DeploymentReading;
171
+ /**
172
+ * The pages by the readers each loses between the two ends of its sharpest
173
+ * question, worst first.
174
+ *
175
+ * Read off the funnel answers handed in, so a page is in this order exactly
176
+ * where that answer put it.
177
+ */
178
+ readonly conversion: DeploymentConversion;
179
+ /**
180
+ * What is wrong with what this deployment collects, page by page.
181
+ *
182
+ * Judged against the schedule handed in, and judging no fold at all where
183
+ * that was `null`.
184
+ */
185
+ readonly health: CollectionHealth;
186
+ /**
187
+ * Whether anything is arriving at this deployment, and what its door turned
188
+ * away.
189
+ *
190
+ * Published whole rather than summarised, because the remedy is on it and
191
+ * nowhere else: `newest.reason` is the deployment's own word for why a
192
+ * delivery was refused, `newest.origin` is the site it came from, and
193
+ * `newest.sinceMs` is what tells a live fault from one fixed a month ago
194
+ * (0326). `AgendaSubject` says what to do; this says what to type.
195
+ *
196
+ * Generic in the reason, which is what keeps that remedy the deployment's:
197
+ * a host hands in its own closed set and gets it back here, where its own
198
+ * exhaustive switch chooses its own sentence. A framework that worded those
199
+ * reasons would be wording a vocabulary it does not define (0311, 0326).
200
+ */
201
+ readonly arrival: ArrivalStanding<TReason>;
202
+ /**
203
+ * The pages by what one fix to each would recover, worst first, and every
204
+ * place the reading of each stopped.
205
+ *
206
+ * The fourth order, in the fourth unit: parts of a page rather than readers.
207
+ * Published beside the fix-list and not inside it — `agenda.first` is
208
+ * untouched by it — because a part is not a reader and the two cannot be
209
+ * ranked against each other (0327, 0377).
210
+ *
211
+ * **It is also the reading the fix-list's rows carry**, and the same object:
212
+ * this rung hands it to `deploymentAgendaOf`, so a row's
213
+ * `AgendaRow.unread` is the row this order published rather than a second
214
+ * reading of one page (0378). That is what keeps a screen drawing the order
215
+ * of places and the fix-list over it from holding two answers about one page
216
+ * — the guarantee the conversion row above is carried under.
217
+ *
218
+ * Its `duplicated` is nought from here, for the reason the order's is: the
219
+ * assembly never holds two readings of one page.
220
+ */
221
+ readonly unread: DeploymentUnread;
222
+ /**
223
+ * The fix-list: the two orders of pages, the measurements to repair, and the
224
+ * one thing to do first.
225
+ *
226
+ * Its `unpaired` counts are nought by construction and its `duplicated` is
227
+ * nought by construction, which is the whole of what this rung guarantees
228
+ * beyond saving the lines.
229
+ *
230
+ * Its `subject` is judged against the refusal rows handed in, so a fix-list
231
+ * read through this rung can never say `unverified` about a deployment that
232
+ * offered a counter.
233
+ */
234
+ readonly agenda: DeploymentAgenda;
235
+ };
236
+ /**
237
+ * Read a deployment's fix-list off a window, its assembly and its funnels.
238
+ *
239
+ * ```ts
240
+ * const assembly = windowAssemblyOf(window, context)
241
+ * const funnels = windowFunnelsOf(window, assembly)
242
+ * const { agenda } = windowAgendaOf(window, assembly, funnels, schedule, turnedAway)
243
+ * ```
244
+ *
245
+ * The window is handed in again rather than carried on the assembly, exactly as
246
+ * the two rungs beside this take it: the door rows all three readings are
247
+ * scaled by are the ones the assembly does not republish, and they are an
248
+ * argument the caller passed one line above.
249
+ *
250
+ * The context is not taken. None of the three readings holds a region bucket or
251
+ * places a form, so neither of the two context fields the figures rung needs has
252
+ * anything to reach here — and the schedule is not a context field, because half
253
+ * of it is the instant the reading is taken and a context that held a clock
254
+ * would answer differently on two calls over one window.
255
+ *
256
+ * @param schedule What the deployment folds within and when this reading is
257
+ * taken, or `null` where it states no schedule and nothing about a stalled fold
258
+ * is to be judged. Required rather than optional, because the reading that is
259
+ * lost by leaving it out is a fault going unreported.
260
+ *
261
+ * It is also where the instant the arrival reading ages its newest refusal
262
+ * against comes from, so that one reading of one window is taken at one
263
+ * instant. A schedule of `null`, or an `at` no parser can read, gives every
264
+ * arrival figure and no age — the shape that reading already takes for a
265
+ * caller that states no instant (0326), and the guard `collection-stalled`
266
+ * already applies to the same field.
267
+ *
268
+ * @param turnedAway What this deployment's door turned away, one row per
269
+ * reason, or `undefined` where it keeps no such counter or none could be read.
270
+ * Required rather than optional on the terms the schedule is: the reading lost
271
+ * by leaving it out is the difference between *nothing to fix* and *nothing to
272
+ * fix it with*, and `undefined` written out is a word a reviewer can read
273
+ * rather than a space where an argument is not (0322, 0343).
274
+ */
275
+ export declare const windowAgendaOf: <TReason extends string = string>(window: ReaderWindow, assembly: WindowAssembly, funnels: WindowFunnels, schedule: CollectionSchedule | null, turnedAway: readonly TurnedAwayTally<TReason>[] | undefined) => WindowAgenda<TReason>;
276
+ //# sourceMappingURL=window-agenda.d.ts.map
@@ -0,0 +1,83 @@
1
+ import { deploymentAgendaOf } from "./agenda.js";
2
+ import { arrivalStandingOf, } from "./arriving.js";
3
+ import { deploymentConversionOf } from "./conversion.js";
4
+ import { deploymentReadingOf } from "./deployment.js";
5
+ import { pageFrontierOf } from "./frontier.js";
6
+ import { collectionHealthOf, } from "./health.js";
7
+ import { readingProgressOf } from "./progress.js";
8
+ import { deploymentUnreadOf } from "./unread.js";
9
+ /**
10
+ * The instant a schedule states, in epoch milliseconds, or `undefined` where it
11
+ * states none this can use.
12
+ *
13
+ * `Date.parse` guarded for `NaN`, which is the same guard
14
+ * {@link collectionHealthOf} puts on the same field — an unreadable instant
15
+ * judges nothing rather than judging against a `NaN`. Here that means every
16
+ * arrival figure and no age, which is a published state of the reading rather
17
+ * than a degraded one (0326).
18
+ */
19
+ const instantOf = (schedule) => {
20
+ if (schedule === null)
21
+ return undefined;
22
+ const at = Date.parse(schedule.at);
23
+ return Number.isNaN(at) ? undefined : at;
24
+ };
25
+ /**
26
+ * Read a deployment's fix-list off a window, its assembly and its funnels.
27
+ *
28
+ * ```ts
29
+ * const assembly = windowAssemblyOf(window, context)
30
+ * const funnels = windowFunnelsOf(window, assembly)
31
+ * const { agenda } = windowAgendaOf(window, assembly, funnels, schedule, turnedAway)
32
+ * ```
33
+ *
34
+ * The window is handed in again rather than carried on the assembly, exactly as
35
+ * the two rungs beside this take it: the door rows all three readings are
36
+ * scaled by are the ones the assembly does not republish, and they are an
37
+ * argument the caller passed one line above.
38
+ *
39
+ * The context is not taken. None of the three readings holds a region bucket or
40
+ * places a form, so neither of the two context fields the figures rung needs has
41
+ * anything to reach here — and the schedule is not a context field, because half
42
+ * of it is the instant the reading is taken and a context that held a clock
43
+ * would answer differently on two calls over one window.
44
+ *
45
+ * @param schedule What the deployment folds within and when this reading is
46
+ * taken, or `null` where it states no schedule and nothing about a stalled fold
47
+ * is to be judged. Required rather than optional, because the reading that is
48
+ * lost by leaving it out is a fault going unreported.
49
+ *
50
+ * It is also where the instant the arrival reading ages its newest refusal
51
+ * against comes from, so that one reading of one window is taken at one
52
+ * instant. A schedule of `null`, or an `at` no parser can read, gives every
53
+ * arrival figure and no age — the shape that reading already takes for a
54
+ * caller that states no instant (0326), and the guard `collection-stalled`
55
+ * already applies to the same field.
56
+ *
57
+ * @param turnedAway What this deployment's door turned away, one row per
58
+ * reason, or `undefined` where it keeps no such counter or none could be read.
59
+ * Required rather than optional on the terms the schedule is: the reading lost
60
+ * by leaving it out is the difference between *nothing to fix* and *nothing to
61
+ * fix it with*, and `undefined` written out is a word a reviewer can read
62
+ * rather than a space where an argument is not (0322, 0343).
63
+ */
64
+ export const windowAgendaOf = (window, assembly, funnels, schedule, turnedAway) => {
65
+ const progress = assembly.readings.pages.map(readingProgressOf);
66
+ const order = deploymentReadingOf(progress, window.pageViews);
67
+ const conversion = deploymentConversionOf(funnels.pages);
68
+ const health = schedule === null
69
+ ? collectionHealthOf(assembly.readings.pages, window.pageViews)
70
+ : collectionHealthOf(assembly.readings.pages, window.pageViews, schedule);
71
+ const arrival = arrivalStandingOf(health, turnedAway, instantOf(schedule));
72
+ const unread = deploymentUnreadOf(assembly.readings.pages.map(pageFrontierOf));
73
+ return {
74
+ progress,
75
+ order,
76
+ conversion,
77
+ health,
78
+ arrival,
79
+ unread,
80
+ agenda: deploymentAgendaOf(order, conversion, health, arrival, unread),
81
+ };
82
+ };
83
+ //# sourceMappingURL=window-agenda.js.map
@@ -0,0 +1,88 @@
1
+ import { type FunnelReach } from "./funnel.js";
2
+ import type { ReaderWindow, WindowAssembly } from "./window.js";
3
+ /**
4
+ * The one reading of a window that the assembly cannot be asked for in one
5
+ * call, published in one call.
6
+ *
7
+ * Assembling a window turns it into the three subjects every reading and
8
+ * comparison takes — the readings, the before-and-afters, the two libraries —
9
+ * and after it almost every reading is one call with one argument
10
+ * ([0327](../../decisions/0327-the-figures-a-window-holds-about-itself-are-a-second-rung-and-a-region-row-set-is-deduplicated-once.md)).
11
+ * A funnel answer is the exception, and it is the exception twice over: it needs
12
+ * the window's funnel rows and its door rows, which the assembly deliberately
13
+ * does not republish, so both the per-page reading and the comparison of two
14
+ * revisions were reachable only by a caller that already knew how to write the
15
+ * composition.
16
+ *
17
+ * **It is not the hazard the second rung's three were.** A funnel answer
18
+ * filters its rows to the revision, scopes them to the form and deduplicates
19
+ * its own questions, so a caller writing the line gets the right answer — the
20
+ * cost is that it is written once per reading and once per side of every
21
+ * comparison, which is how one screen comes to hold two answers to one
22
+ * question.
23
+ *
24
+ * ## What this adds beyond saving the line
25
+ *
26
+ * **Every side of every comparison is the same object as the reading of that
27
+ * form.** The sides of a before-and-after are two of the readings the window
28
+ * holds, so their answers are looked up rather than read a second time, and a
29
+ * surface drawing the reading and the comparison together cannot show two
30
+ * funnel answers of one revision. That is the same property the second rung
31
+ * keeps between a region map and a readership (0327), one subject across.
32
+ *
33
+ * ## It composes and does not count
34
+ *
35
+ * Nothing here counts, divides, sums or withholds. Each answer carries its own
36
+ * counts of what it ignored — rows of another revision, of another form, and
37
+ * questions named twice — and a total over them would be a figure in no unit
38
+ * (0327). A pair whose side is not among the readings is read rather than
39
+ * dropped, so there is nothing to report a count of.
40
+ *
41
+ * Linear in the readings and their rows, being one funnel answer per reading
42
+ * and one lookup per side of a pair.
43
+ */
44
+ /** Two revisions of one form, as their funnels answered. */
45
+ export type FunnelPairing = {
46
+ readonly was: FunnelReach;
47
+ readonly now: FunnelReach;
48
+ };
49
+ /** A window's funnels, read against the pages and the arrivals the window holds. */
50
+ export type WindowFunnels = {
51
+ /**
52
+ * One answer per reading the window holds, in the readings' own order.
53
+ *
54
+ * Never two of one reading, because the readings are never two of one: the
55
+ * key a window is split by is the key an answer is of (0290).
56
+ */
57
+ readonly pages: readonly FunnelReach[];
58
+ /**
59
+ * One before-and-after per form the window paired, in the pairs' own order.
60
+ *
61
+ * What a comparison of two windows' funnels takes (0288), which could not be
62
+ * reached from a store before: the pairing exists and the answers it needs
63
+ * did not.
64
+ */
65
+ readonly pairs: readonly FunnelPairing[];
66
+ };
67
+ /**
68
+ * Read a window's funnels off the window and its assembly.
69
+ *
70
+ * ```ts
71
+ * const assembly = windowAssemblyOf(window, context)
72
+ * const funnels = windowFunnelsOf(window, assembly)
73
+ *
74
+ * const order = deploymentConversionOf(funnels.pages)
75
+ * const moved = funnels.pairs.map(({ was, now }) => funnelChangeOf(was, now))
76
+ * ```
77
+ *
78
+ * The window is handed in again rather than carried on the assembly, exactly as
79
+ * the second rung takes it: the rows these answers are of are the ones the
80
+ * assembly does not republish, and they are an argument the caller passed one
81
+ * line above.
82
+ *
83
+ * The context is not needed and is not taken. A funnel answer is scoped by the
84
+ * form its reading names and holds no region bucket, so neither of the two
85
+ * context fields the other rungs need has anything to reach here.
86
+ */
87
+ export declare const windowFunnelsOf: (window: ReaderWindow, assembly: WindowAssembly) => WindowFunnels;
88
+ //# sourceMappingURL=window-funnels.d.ts.map
@@ -0,0 +1,47 @@
1
+ import { readingKeyOf } from "./audiences.js";
2
+ import { funnelReachOf } from "./funnel.js";
3
+ /**
4
+ * Read a window's funnels off the window and its assembly.
5
+ *
6
+ * ```ts
7
+ * const assembly = windowAssemblyOf(window, context)
8
+ * const funnels = windowFunnelsOf(window, assembly)
9
+ *
10
+ * const order = deploymentConversionOf(funnels.pages)
11
+ * const moved = funnels.pairs.map(({ was, now }) => funnelChangeOf(was, now))
12
+ * ```
13
+ *
14
+ * The window is handed in again rather than carried on the assembly, exactly as
15
+ * the second rung takes it: the rows these answers are of are the ones the
16
+ * assembly does not republish, and they are an argument the caller passed one
17
+ * line above.
18
+ *
19
+ * The context is not needed and is not taken. A funnel answer is scoped by the
20
+ * form its reading names and holds no region bucket, so neither of the two
21
+ * context fields the other rungs need has anything to reach here.
22
+ */
23
+ export const windowFunnelsOf = (window, assembly) => {
24
+ const answerOf = (reading) => funnelReachOf(reading, window.funnels, window.pageViews);
25
+ const pages = assembly.readings.pages.map(answerOf);
26
+ const byReading = new Map(pages.map((answer) => [readingKeyOf(answer), answer]));
27
+ /**
28
+ * A side's answer, reused where the window holds that reading and read where
29
+ * it does not.
30
+ *
31
+ * Reused for the property above: two answers of one revision on one screen is
32
+ * the thing this exists to make impossible. Read rather than skipped for the
33
+ * caller that assembled a pairing of its own — a side absent from the
34
+ * readings is still a revision whose funnels can be answered, and dropping it
35
+ * would publish *this form has no before-and-after* about a pair that has
36
+ * one.
37
+ */
38
+ const sideOf = (reading) => byReading.get(readingKeyOf(reading)) ?? answerOf(reading);
39
+ return {
40
+ pages,
41
+ pairs: assembly.pairs.pairs.map((pair) => ({
42
+ was: sideOf(pair.was),
43
+ now: sideOf(pair.now),
44
+ })),
45
+ };
46
+ };
47
+ //# sourceMappingURL=window-funnels.js.map
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Serving a stored page without reading its row every time, and being told the
3
+ * moment the row moves.
4
+ *
5
+ * A page the store governs costs one read per reader. A cache over that read is
6
+ * only honest if something clears it when the log grows, because the
7
+ * alternative — a window, a short interval, a build-time copy — serves a
8
+ * revision somebody has already replaced and calls it current. These are the
9
+ * two halves of being told instead: a read-through wrapper over `head`, an
10
+ * invalidating wrapper over `append`, and one tag both derive the same way so
11
+ * that neither can be wrong about which entry belongs to which tree.
12
+ *
13
+ * Neither half knows what the cache is. A host hands in a read-through and a
14
+ * way to invalidate a tag; what sits behind them is its own business, which is
15
+ * what keeps this module free of any framework.
16
+ */
17
+ import type { TreeId } from "../ids.js";
18
+ import type { TreeStore } from "./store.js";
19
+ /**
20
+ * The tag a cached reading of one tree carries.
21
+ *
22
+ * Derived rather than written down, because the reader and the writer are in
23
+ * different places — on this deployment a public page and a portal action, and
24
+ * on a host's they may be two applications — and a tag spelled twice is a cache
25
+ * that stops being cleared the day one of the two spellings is edited.
26
+ */
27
+ export declare const treeCacheTag: (treeId: TreeId) => string;
28
+ /**
29
+ * Where a host's cache is reached, and the one obligation on it.
30
+ *
31
+ * `load` produces the value to remember, under `key`, filed against `tags`. A
32
+ * host is free to answer from a previous call with the same `key`, and is
33
+ * expected to drop every entry carrying a tag it is told to invalidate.
34
+ *
35
+ * **A rejecting `load` must not be remembered.** Rejection is the only way this
36
+ * seam can say *do not keep this one*, and it is the only signal a read-through
37
+ * cache is able to honour: by the time there is a value to judge, the cache has
38
+ * been asked for it and a `put` it could decline does not exist. So a read that
39
+ * the store refused is raised rather than returned, and the wrapper below turns
40
+ * it back into the refusal the caller is owed.
41
+ */
42
+ export interface TreeCache {
43
+ readonly readThrough: (key: readonly string[], tags: readonly string[], load: () => Promise<unknown>) => Promise<unknown>;
44
+ }
45
+ /**
46
+ * A handle whose `head` is answered from a cache, and whose other reads are not.
47
+ *
48
+ * ## Why `head` alone
49
+ *
50
+ * It is the read a visitor waits for. A page the store governs is one `head`
51
+ * and a render, so on a surface that serves pages this is the whole of what a
52
+ * cache can recover — and the cost of being wrong about it is bounded by the
53
+ * invalidation below, which is keyed by exactly the tree a `head` names.
54
+ *
55
+ * `revisions` is a history screen, where a reader is asking what happened and
56
+ * is owed the answer as it is now. `list` is the one that could not be cached
57
+ * correctly even if it were worth it: it spans trees, so no tag derived from a
58
+ * tree id can clear it, and a page list that keeps a page somebody has since
59
+ * added is a worse screen than a slow one.
60
+ *
61
+ * ## Writes pass through
62
+ *
63
+ * `create` and `append` are forwarded untouched. Invalidation is a separate
64
+ * wrapper because the two compose in either order and over different handles:
65
+ * on this deployment the writing handle is not the handle a page is read
66
+ * through, and a store that cached its own writes away would still have to be
67
+ * told about everybody else's.
68
+ */
69
+ export declare const cachingTreeStore: (store: TreeStore, cache: TreeCache) => TreeStore;
70
+ /**
71
+ * A handle that tells a cache the log grew, every time it does.
72
+ *
73
+ * ## Why here rather than on the event stream
74
+ *
75
+ * The runtime narrates a commit, and a host could listen for it. This sits on
76
+ * the store instead, because what a cache has to track is not *a change was
77
+ * accepted* but *this row is not what it was* — and the second is true of every
78
+ * append, including the ones that never went near a composition: a revert, a
79
+ * reseed, a migration, a host's own script. Wrapping the store catches the
80
+ * category; wrapping the runtime catches whichever members of it happen to be
81
+ * proposed.
82
+ *
83
+ * ## `create` is not an invalidation
84
+ *
85
+ * Nothing cached can be wrong about a tree that has just come into existence,
86
+ * because the wrapper above remembers only trees it was handed and a refusal is
87
+ * never remembered. An absent page therefore stays absent for exactly as long
88
+ * as it is absent, and the first reader after a seed reads the row.
89
+ *
90
+ * ## A cache that cannot be told does not lose a write
91
+ *
92
+ * `invalidate` is called after the append succeeded, and a throw from it is
93
+ * contained. The write is already history by then: raising it would report a
94
+ * durable change as a failure, and the caller would be entitled to retry
95
+ * something that has already happened. What the containment costs is a stale
96
+ * entry nobody is told about — so a host whose invalidation can fail should
97
+ * make the failure visible on its own side, where there is something to say
98
+ * about it.
99
+ */
100
+ export declare const invalidatingTreeStore: (store: TreeStore, invalidate: (tag: string) => void) => TreeStore;
101
+ //# sourceMappingURL=cache.d.ts.map