@jam-overture/loom 0.1.0 → 0.2.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 (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -1,7 +1,9 @@
1
+ import type { AudienceId } from "../audience/audience.js";
1
2
  import type { TreeId } from "../ids.js";
2
3
  import type { Result } from "../result.js";
3
- import type { FunnelAnswer, ReaderTally } from "./rollup.js";
4
4
  import type { ReaderSignalStoreError } from "./journal.js";
5
+ import type { RevisionViews, StoredPageViews } from "./page-views.js";
6
+ import type { FunnelAnswer, ReaderTally } from "./rollup.js";
5
7
  /**
6
8
  * Where the counters live once the batches they came from are gone.
7
9
  *
@@ -24,18 +26,49 @@ import type { ReaderSignalStoreError } from "./journal.js";
24
26
  * the alternative is keeping view keys in durable storage — which is the thing
25
27
  * 0146 refuses. A deployment that wants the bound small makes the rollup window
26
28
  * long relative to a page view, which is the default.
29
+ *
30
+ * **The bound is now also a measurement, and that is the one thing here that has
31
+ * changed since 0147.** Page views are counted a second time at the door, where
32
+ * an opening is a single event rather than a distinct count
33
+ * ([`page-views.ts`](page-views.ts)), so the difference between the two numbers
34
+ * is the straddle — per revision, in the rows, for as long as the counters live.
35
+ * It does not make a tally exact. It makes a deployment able to say by how much
36
+ * it is not.
37
+ */
38
+ /**
39
+ * One node's line as the store keeps it, which is a tally plus the audience it
40
+ * was collected under and when it last changed.
41
+ *
42
+ * `audienceId` is on the stored row and not on `ReaderTally` deliberately
43
+ * (0284). A rollup folds one audience's window, so the counters it produces are
44
+ * already all one audience's and a field on each would be the same value
45
+ * repeated; a row read back may sit beside another audience's, so it has to say
46
+ * which it is. It is also what lets a screen compare two without a reading
47
+ * having to remember what it asked for.
27
48
  */
28
- /** One node's line as the store keeps it, which is a tally plus when it last changed. */
29
49
  export type StoredTally = ReaderTally & {
50
+ readonly audienceId: AudienceId;
30
51
  readonly updatedAt: string;
31
52
  };
32
- /** One funnel answer as the store keeps it. */
53
+ /** One funnel answer as the store keeps it. See `StoredTally.audienceId`. */
33
54
  export type StoredFunnel = FunnelAnswer & {
55
+ readonly audienceId: AudienceId;
34
56
  readonly updatedAt: string;
35
57
  };
36
58
  export type TallyReadRequest = {
37
59
  /** Absent reads every tree the handle can see, which is the scope rule (0020). */
38
60
  readonly treeId?: TreeId;
61
+ /**
62
+ * Absent reads every audience (0284).
63
+ *
64
+ * A filter rather than a requirement, on the terms `revision` below is one:
65
+ * comparing two audiences is the point of serving two, so a reading that
66
+ * could not span them would make the comparison the measurement rests on
67
+ * unreadable (0263). Each row names its own audience, so a caller that wants them
68
+ * apart groups rather than summing — and a caller that sums two has asked
69
+ * for one number about two populations.
70
+ */
71
+ readonly audience?: AudienceId;
39
72
  /**
40
73
  * Absent reads every revision.
41
74
  *
@@ -46,6 +79,36 @@ export type TallyReadRequest = {
46
79
  */
47
80
  readonly revision?: number;
48
81
  };
82
+ /**
83
+ * The one write the door makes into the durable counters.
84
+ *
85
+ * Narrow on purpose. Everything else here is written by a rollup over a window
86
+ * of the buffer; the number of page views that *began* cannot be, because by
87
+ * the time a window is folded nothing knows which of its views were already
88
+ * underway (0214). So the intake writes that one counter, and it is handed an
89
+ * interface that can do nothing else — a door that could read a deployment's
90
+ * tallies is a public endpoint one query away from serving them.
91
+ */
92
+ export interface ReaderOpeningCounter {
93
+ /**
94
+ * Add the page views a delivery opened, creating rows that do not exist yet.
95
+ *
96
+ * Additive like everything else in this file, and for the sharpest reason of
97
+ * any of them: every call is one delivery's worth of arrivals, so a store
98
+ * that replaced would report the last reader rather than the readership.
99
+ */
100
+ readonly opened: (openings: readonly RevisionViews[], at: string,
101
+ /**
102
+ * The audience the delivery was served under (0284). Omitted is
103
+ * `aud_everyone`, so a door that serves one form of every page calls this
104
+ * exactly as it did.
105
+ *
106
+ * One audience per call rather than one per opening, because a delivery is
107
+ * one page view of one form of one page — the same reason the batch carries
108
+ * it and a signal does not.
109
+ */
110
+ audience?: AudienceId) => Promise<Result<void, ReaderSignalStoreError>>;
111
+ }
49
112
  /**
50
113
  * Counters are not paged.
51
114
  *
@@ -54,17 +117,83 @@ export type TallyReadRequest = {
54
117
  * Paging them would be a cursor every caller has to carry for a result that
55
118
  * fits in a response.
56
119
  */
57
- export interface ReaderTallyStore {
120
+ /**
121
+ * One fold's output, as a caller hands it over.
122
+ *
123
+ * Every row in it belongs to one audience, which is what keeps `ReaderTally`
124
+ * free of the dimension (0284): a window holding two audiences is folded once
125
+ * per audience, and each fold produces one of these.
126
+ */
127
+ export type AppliedCounters = {
128
+ readonly tallies: readonly ReaderTally[];
129
+ readonly funnels: readonly FunnelAnswer[];
58
130
  /**
59
- * Add a rollup's counters to what is already there, creating rows that do not
60
- * exist yet. Atomic over the whole rollup where the backend can be: a partly
61
- * applied window is counters that disagree with each other.
131
+ * The window's page views, per revision, for the counter the exact count
132
+ * is compared against.
133
+ *
134
+ * Optional, and absent is not none: a caller applying counters it
135
+ * composed itself — a backfill, a fixture, a test — has no window to
136
+ * report, and a nought written there would read as *no page views* and
137
+ * make a reading claim the node counters were exact.
62
138
  */
63
- readonly apply: (rollup: {
64
- readonly tallies: readonly ReaderTally[];
65
- readonly funnels: readonly FunnelAnswer[];
66
- }, at: string) => Promise<Result<void, ReaderSignalStoreError>>;
139
+ readonly appearances?: readonly RevisionViews[];
140
+ };
141
+ /** One audience's share of a window, which is what {@link ReaderTallyStore.applyWindow} takes a list of. */
142
+ export type AudienceCounters = AppliedCounters & {
143
+ /** The audience this fold was taken over (0284). Omitted is `aud_everyone`. */
144
+ readonly audience?: AudienceId;
145
+ };
146
+ export interface ReaderTallyStore extends ReaderOpeningCounter {
147
+ /**
148
+ * Add a whole window's counters to what is already there, every audience in
149
+ * it, in one atomic write — creating rows that do not exist yet.
150
+ *
151
+ * **This is the method a collection run calls, and the atomicity is the
152
+ * reason it exists rather than a property it happens to have.**
153
+ *
154
+ * A window holds whatever arrived in it, so a deployment serving two forms of
155
+ * a page holds two audiences interleaved and is folded once per audience
156
+ * (0284). Writing those folds as separate calls leaves a state between them
157
+ * where some are durable and the rest are not — and because counting and
158
+ * forgetting are one operation (`collect.ts`), the buffer still holds the
159
+ * window, so the next run folds it again and **adds the already-durable
160
+ * audiences a second time.** Of a tally's nine counters, `views`, `reached`
161
+ * and `engaged` are distinct counts and would move little; `dwellMs`,
162
+ * `activations`, `opens`, `closes` and `completions` are occurrences and
163
+ * would double, which every rate in this subsystem divides by the first kind
164
+ * — so the damage is invisible, permanent (0158) and looks like a readership
165
+ * twice as interested as it was (0316).
166
+ *
167
+ * So the window is one write or it is none. A store that cannot be atomic
168
+ * over several audiences cannot be correct here, which is why this is a
169
+ * required method rather than a capability a caller probes for.
170
+ *
171
+ * Two entries naming one audience are added together, not refused: the
172
+ * guarantee is the same one `counters.ts` gives for two rows naming one
173
+ * counter, and it is here so that the two shipped stores cannot disagree
174
+ * about it.
175
+ */
176
+ readonly applyWindow: (window: readonly AudienceCounters[], at: string) => Promise<Result<void, ReaderSignalStoreError>>;
177
+ /**
178
+ * One audience's counters, which is {@link applyWindow} over a single entry
179
+ * and is implemented as exactly that in both shipped stores — so the two
180
+ * cannot drift on the half that matters.
181
+ *
182
+ * Kept because a caller composing counters by hand — a backfill, a fixture, a
183
+ * migration — has one audience and no window, and should not have to wrap it
184
+ * in a list to say so.
185
+ */
186
+ readonly apply: (counters: AppliedCounters, at: string,
187
+ /**
188
+ * The audience whose counters these are (0284). Omitted is `aud_everyone`.
189
+ */
190
+ audience?: AudienceId) => Promise<Result<void, ReaderSignalStoreError>>;
67
191
  readonly tallies: (request?: TallyReadRequest) => Promise<Result<readonly StoredTally[], ReaderSignalStoreError>>;
68
192
  readonly funnels: (request?: TallyReadRequest) => Promise<Result<readonly StoredFunnel[], ReaderSignalStoreError>>;
193
+ /**
194
+ * How many page views there were, which is the denominator every rate on a
195
+ * screen needs and the only row here written from two sides.
196
+ */
197
+ readonly pageViews: (request?: TallyReadRequest) => Promise<Result<readonly StoredPageViews[], ReaderSignalStoreError>>;
69
198
  }
70
199
  //# sourceMappingURL=tally.d.ts.map
@@ -0,0 +1,148 @@
1
+ import type { LibraryPace, LibraryPaceOptions } from "./library-pace.js";
2
+ import { type RegionPagesReading } from "./region-pages.js";
3
+ import { type ReadingSilence, type SilenceCensus } from "./silence-census.js";
4
+ import { type DeploymentReadingContext, type ReaderWindow, type WindowAssembly } from "./window.js";
5
+ /**
6
+ * The second rung: the figures a window holds about **itself**, rather than
7
+ * about one of the subjects the assembly under this publishes.
8
+ *
9
+ * `windowAssemblyOf` turns a window into the three subjects every reading and
10
+ * comparison takes — the readings, the pairs, the two libraries — and after it,
11
+ * forty of the forty-two readings are **one call with one argument**:
12
+ * `reachOf(readings.pages[0])`, `libraryChangeOf(libraries.was.readings,
13
+ * libraries.now.readings)`. Nothing can be composed wrongly, because there is
14
+ * nothing to compose.
15
+ *
16
+ * **Three were not.** `regionPagesOf` (§62), `silenceCensusOf` (§63) and
17
+ * `libraryPaceOf` (§64) each need something the assembly does not publish, and
18
+ * all three were therefore reachable only by a caller that already knew they
19
+ * existed. That was filed as one gap each and then as a pattern, with a
20
+ * recommendation that a run take all three at once rather than adding any of
21
+ * them individually — because each of the three composes in a way that
22
+ * **type-checks, runs, and is wrong without saying so**:
23
+ *
24
+ * ```ts
25
+ * // All three of these compile.
26
+ * regionPagesOf(window.regions ?? [], { floor: DEFAULT_REGION_FLOOR })
27
+ * libraryPaceOf(libraries.now.readings, window.pageViews)
28
+ * silenceCensusOf(pages.map((page) => ({ meaning: meaningOfKindSilence(…) })))
29
+ * ```
30
+ *
31
+ * ## The three things a caller writing those lines gets wrong
32
+ *
33
+ * **A region row set has to be deduplicated before it is read, and the floor
34
+ * has to be the deployment's own.** Two readings of one window's regions are
35
+ * published here — the assembly's `readership` map and this breakdown by page —
36
+ * and they are built from the same rows at the same floor, so they must drop the
37
+ * same repeats. The assembly's does (`distinctRegionRows`); a caller handing
38
+ * `window.regions` straight to `regionPagesOf` does not, and a doubled bucket
39
+ * is worse than a wrong number: it **clears a floor it should not have
40
+ * cleared**, so a place with too few readers to name gets named (0146, 0158).
41
+ * The floor comes off the context for the same reason — a number typed at this
42
+ * call site can differ from the one the assembly's maps were read at, and then
43
+ * one window has two readerships.
44
+ *
45
+ * **`?? []` is the wrong collapse.** {@link ReaderWindow.regions} is
46
+ * `undefined` where no region store was offered and `[]` where one answered
47
+ * with nothing, and those are two sentences: *we cannot say where your readers
48
+ * are* and *you have no readers abroad* (0240, 0309). So the figure is
49
+ * `undefined` or a reading, carried exactly as the window carries it.
50
+ *
51
+ * **A kind's pace is over the window's readings and not over a library.** Every
52
+ * other reading of a kind takes `libraries.was` or `libraries.now`, so the
53
+ * nearest line to hand is the wrong one: a side of a library holds one reading
54
+ * per form, which drops the earlier revision of every page revised inside the
55
+ * window and every form the placings could not place. `libraryPaceOf` is a
56
+ * reading rather than a comparison, so its evidence is every reading the window
57
+ * holds.
58
+ *
59
+ * ## What the census is over, which is the only thing a caller chooses
60
+ *
61
+ * A census's denominator is *the readings somebody is looking at*, and this
62
+ * cannot know what a surface draws. So {@link WindowFigures.census} is over the
63
+ * entries the caller handed in **plus the rows of the pace this took**, and the
64
+ * list it was taken over is published beside it so that a caller may take a
65
+ * narrower one. The caller's entries come first, so where a state is reported by
66
+ * both it keeps the caller's vocabulary — its readings are the ones on the
67
+ * screen (0324).
68
+ *
69
+ * What this adds is the mapping, which is the part nothing reminded anybody of:
70
+ * each of the pace's kind rows is mapped through `meaningOfKindPaceSilence` and
71
+ * attributed to **no page**, because a kind is not a page and putting it on a
72
+ * form would be a guess (0324, 0240).
73
+ *
74
+ * ## It composes and does not count
75
+ *
76
+ * Nothing here counts, divides, sums or withholds — the rule the four steps
77
+ * under it keep. It decides **which rows each of three published readings is
78
+ * entitled to** and calls them. In particular there is no total of what the
79
+ * three left out: a withheld region bucket, a kind with no pace and a silent
80
+ * reading are three different absences in three different units, and a sum over
81
+ * them would be a figure in none.
82
+ *
83
+ * **It is not where `arrivalStandingOf` goes.** A refusal is not in a window at
84
+ * all — it is the deployment's own counter, keyed by application and reason,
85
+ * written on the request path and holding nothing a window holds (0309, 0326).
86
+ * Carrying its result through as a field would add no figure and would make this
87
+ * whole type generic in a deployment's refusal reasons for one passthrough. A
88
+ * surface that wants both calls both.
89
+ *
90
+ * Linear in the window, being one pass for the rows and one reading each.
91
+ */
92
+ /** What a window says about itself, once its subjects have been assembled. */
93
+ export type WindowFigures = {
94
+ /**
95
+ * Where the readers were and what the readers of each place read, or
96
+ * `undefined` where no region store was offered.
97
+ *
98
+ * Its `map` is the assembly's `readings.regions.readership` — the same rows at
99
+ * the same floor — so a surface drawing both cannot show two readerships of
100
+ * one window.
101
+ */
102
+ readonly regions: RegionPagesReading | undefined;
103
+ /** What the library asks of its readers' time, by kind of part, over every reading the window holds. */
104
+ readonly pace: LibraryPace;
105
+ /**
106
+ * The states this window is in, over the caller's readings and the pace's own
107
+ * rows.
108
+ *
109
+ * `census.readings === silences.length`, which is the identity that says the
110
+ * denominator is the published list and nothing else.
111
+ */
112
+ readonly census: SilenceCensus;
113
+ /**
114
+ * Every entry the census was taken over, the caller's first and then the
115
+ * pace's, so a caller may slice it and take a census of its own.
116
+ */
117
+ readonly silences: readonly ReadingSilence[];
118
+ };
119
+ /** What the figures are read at, beyond what the context already says. */
120
+ export type WindowFigureOptions = LibraryPaceOptions & {
121
+ /**
122
+ * The silences of the readings the caller took over this window's subjects,
123
+ * one entry per reading and each already mapped through its own vocabulary's
124
+ * `meaningOf…Silence`.
125
+ *
126
+ * A reading that answered is handed in with `meaning: null` rather than left
127
+ * out, which is what gives a page's readings a denominator (0324). Left out
128
+ * entirely, the census is over the pace's rows alone — which is a true census
129
+ * of what this rung computed and not of what a screen shows.
130
+ */
131
+ readonly silences?: readonly ReadingSilence[];
132
+ };
133
+ /**
134
+ * Read the figures a window holds about itself off one call.
135
+ *
136
+ * ```ts
137
+ * const assembly = windowAssemblyOf(window, context)
138
+ * const figures = windowFiguresOf(window, assembly, context)
139
+ * ```
140
+ *
141
+ * The window and the context are handed in again rather than carried on the
142
+ * assembly: two of the three readings here are of **rows** the assembly
143
+ * deliberately does not republish, and the floor has to be the one the
144
+ * assembly's own maps were read at. Both are arguments the caller passed one
145
+ * line above, so nothing is gone looking for.
146
+ */
147
+ export declare const windowFiguresOf: (window: ReaderWindow, assembly: WindowAssembly, context: DeploymentReadingContext, options?: WindowFigureOptions) => WindowFigures;
148
+ //# sourceMappingURL=window-figures.d.ts.map
@@ -0,0 +1,42 @@
1
+ import { libraryPaceOf } from "./library-pace.js";
2
+ import { regionPagesOf } from "./region-pages.js";
3
+ import { silenceCensusOf } from "./silence-census.js";
4
+ import { meaningOfKindPaceSilence } from "./silences.js";
5
+ import { distinctRegionRows, } from "./window.js";
6
+ /** One census entry per kind row, of no page, because a kind is not a page. */
7
+ const silencesOfPace = (pace) => [...pace.byType, ...pace.byRole].map((row) => ({
8
+ meaning: row.silence === null ? null : meaningOfKindPaceSilence(row.silence),
9
+ form: null,
10
+ }));
11
+ /**
12
+ * Read the figures a window holds about itself off one call.
13
+ *
14
+ * ```ts
15
+ * const assembly = windowAssemblyOf(window, context)
16
+ * const figures = windowFiguresOf(window, assembly, context)
17
+ * ```
18
+ *
19
+ * The window and the context are handed in again rather than carried on the
20
+ * assembly: two of the three readings here are of **rows** the assembly
21
+ * deliberately does not republish, and the floor has to be the one the
22
+ * assembly's own maps were read at. Both are arguments the caller passed one
23
+ * line above, so nothing is gone looking for.
24
+ */
25
+ export const windowFiguresOf = (window, assembly, context, options = {}) => {
26
+ const pace = libraryPaceOf(assembly.readings.pages, window.pageViews, {
27
+ ...(options.wordsPerMinute === undefined ? {} : { wordsPerMinute: options.wordsPerMinute }),
28
+ });
29
+ const silences = [
30
+ ...(options.silences ?? []),
31
+ ...silencesOfPace(pace),
32
+ ];
33
+ return {
34
+ regions: window.regions === undefined
35
+ ? undefined
36
+ : regionPagesOf(distinctRegionRows(window.regions).kept, { floor: context.floor }),
37
+ pace,
38
+ census: silenceCensusOf(silences),
39
+ silences,
40
+ };
41
+ };
42
+ //# sourceMappingURL=window-figures.js.map