@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
@@ -0,0 +1,287 @@
1
+ import { z } from "zod";
2
+ import type { AudienceId } from "../audience/audience.js";
3
+ import type { TreeId } from "../ids.js";
4
+ import type { Result } from "../result.js";
5
+ import type { ReaderSignalStoreError } from "./journal.js";
6
+ import type { RevisionOf, RevisionViews } from "./page-views.js";
7
+ import type { TallyReadRequest } from "./tally.js";
8
+ /**
9
+ * A region nobody can name.
10
+ *
11
+ * A deployment behind a proxy that adds no such header, a request from a
12
+ * development machine, a header holding something that is not a country code —
13
+ * all of them are this, and it is a bucket rather than a dropped row. *We do
14
+ * not know where 40 of these views came from* is a fact about the measurement;
15
+ * silently keeping only the views that could be placed is a figure that looks
16
+ * complete and is not.
17
+ *
18
+ * Seven characters, so it can never collide with a two-letter code.
19
+ */
20
+ export declare const UNKNOWN_REGION: ReaderRegion;
21
+ /** Two uppercase letters, which is what a country code is. */
22
+ export declare const regionPattern: RegExp;
23
+ /**
24
+ * A country, or the admission that there is none.
25
+ *
26
+ * Deliberately no narrower. A subdivision or a city is the step from *where our
27
+ * readers are* to *who that reader was* — a city plus a count of two is a
28
+ * person with an address — and the header carrying one is sitting beside the
29
+ * header this reads. It is not read.
30
+ *
31
+ * Deliberately no wider either: the value becomes a column, and a column fed
32
+ * from a request header is a column a caller can write to. Two letters or the
33
+ * one sentinel is a closed set, so the worst a poisoned header can do is add to
34
+ * a bucket that already exists.
35
+ */
36
+ export declare const readerRegionSchema: z.ZodBranded<z.ZodUnion<[z.ZodLiteral<"unknown">, z.ZodString]>, "ReaderRegion">;
37
+ export type ReaderRegion = z.infer<typeof readerRegionSchema>;
38
+ /**
39
+ * Read a region off whatever the platform wrote, and never fail.
40
+ *
41
+ * Trimmed and upper-cased because headers are written by whoever is in front of
42
+ * the application and casing is not a thing to have an opinion about. Anything
43
+ * that is not a country code — absent, empty, a city, a word, the Tor marker
44
+ * some platforms send — is unplaced rather than refused: this runs on the
45
+ * request path of the one public write endpoint, and a region that cannot be
46
+ * read is a bucket, not an error.
47
+ */
48
+ export declare const readerRegionOf: (given: string | null | undefined) => ReaderRegion;
49
+ /**
50
+ * Page views from one region, of one revision of one tree.
51
+ *
52
+ * Keyed the way every durable counter in this subsystem is keyed — a signal
53
+ * about the fourth section means nothing once a proposal has moved it — so a
54
+ * region's number is answerable before and after a change rather than smeared
55
+ * across both.
56
+ */
57
+ export type ReaderRegionCount = {
58
+ readonly treeId: TreeId;
59
+ readonly revision: number;
60
+ readonly region: ReaderRegion;
61
+ /** Page views that *began* here, so a longer visit is not a bigger number. */
62
+ readonly views: number;
63
+ };
64
+ /**
65
+ * A region count as the store keeps it: the count, the audience it was
66
+ * collected under, and when it last moved. See `StoredTally.audienceId` (0284).
67
+ */
68
+ export type StoredRegionCount = ReaderRegionCount & {
69
+ readonly audienceId: AudienceId;
70
+ readonly updatedAt: string;
71
+ };
72
+ /**
73
+ * The durable half, and the only one there is — a region has no raw form to
74
+ * expire, because it was never written down as an observation.
75
+ *
76
+ * Written by the intake, on the request path, which is what distinguishes this
77
+ * from the per-node counters: those are written by a rollup over a window, and
78
+ * a region cannot be, because by then the request it was read from is gone.
79
+ */
80
+ export interface ReaderRegionStore {
81
+ /**
82
+ * Add views to the buckets they belong in, creating rows that do not exist
83
+ * yet. Additive for the same reason applying a rollup is: every call reports
84
+ * what just arrived rather than what is true so far.
85
+ */
86
+ readonly count: (counts: readonly ReaderRegionCount[], at: string,
87
+ /** The audience the delivery was served under (0284). Omitted is `aud_everyone`. */
88
+ audience?: AudienceId) => Promise<Result<void, ReaderSignalStoreError>>;
89
+ readonly regions: (request?: TallyReadRequest) => Promise<Result<readonly StoredRegionCount[], ReaderSignalStoreError>>;
90
+ }
91
+ /**
92
+ * What one delivery adds, which is one view per page view it opened.
93
+ *
94
+ * **It is handed the openings rather than the delivery**, so that a region can
95
+ * only ever be a stamp on a page view somebody already counted. The walk that
96
+ * finds them, and the deduplication that makes a retried opening one arrival
97
+ * rather than two, is `openingsOf` in `page-views.ts` — shared deliberately,
98
+ * because two counters that each decided for themselves how many readers
99
+ * arrived would sooner or later disagree about it, and the disagreement would
100
+ * surface as a map whose numbers do not add up to the number of page views
101
+ * there were.
102
+ *
103
+ * A delivery that opened nothing adds nothing, and a sender that never says
104
+ * adds nothing at all — which is the honest answer for a batch synthesised on a
105
+ * server or replayed from a fixture, exactly as such a batch adds nothing to
106
+ * any view count.
107
+ */
108
+ export declare const regionCountsOf: (openings: readonly RevisionViews[], region: ReaderRegion) => readonly ReaderRegionCount[];
109
+ /**
110
+ * The smallest a bucket may be before it is named.
111
+ *
112
+ * Twenty-five, and the number is a judgement rather than a derivation: it is
113
+ * low enough that a deployment with a few hundred readers sees its own map, and
114
+ * high enough that no bucket is one person, one household or one office. A
115
+ * deployment that wants more caution raises it.
116
+ *
117
+ * It is not lowerable, and that is the one place this subsystem overrides an
118
+ * operator. The floor is what makes the aggregate an aggregate; a deployment
119
+ * that could set it to one would be running a different product, and the
120
+ * difference would be invisible on the screen that showed the result.
121
+ */
122
+ export declare const DEFAULT_REGION_FLOOR = 25;
123
+ /**
124
+ * The floor that will actually be used, given what somebody asked for.
125
+ *
126
+ * Raise-only, and anything that is not a whole number of views is the default —
127
+ * a floor read from configuration is read from a string somebody typed, and the
128
+ * direction to be wrong in is the cautious one.
129
+ */
130
+ export declare const regionFloorOf: (asked: number | undefined) => number;
131
+ /** One region, as a reading reports it. */
132
+ export type RegionBucket = {
133
+ readonly region: ReaderRegion;
134
+ readonly views: number;
135
+ };
136
+ export type RegionReading = {
137
+ /** The floor the rows were read at, so a screen can say what it is withholding by. */
138
+ readonly floor: number;
139
+ /**
140
+ * The audience whose arrivals this map is of, or `null` where nothing said.
141
+ *
142
+ * {@link regionReadingFor} names it, because it picked the rows of one
143
+ * audience to build the map from. {@link regionReadingOf} leaves it `null`,
144
+ * because it groups whatever it is handed and a deployment's whole window is
145
+ * a readership rather than one form's.
146
+ *
147
+ * Carried so that a comparison of two maps can refuse a pair of two
148
+ * populations (0284). It is the one thing a readership comparison cannot
149
+ * derive and the one thing that makes it a comparison of like with like.
150
+ *
151
+ * What the map **summed** is the other field, and the two are not the same
152
+ * question: see {@link RegionReading.audiences}.
153
+ */
154
+ readonly audienceId: AudienceId | null;
155
+ /**
156
+ * Every audience the rows this map summed named, deduplicated and in a stable
157
+ * order.
158
+ *
159
+ * The same census `PageReading.audiences` publishes over a window of tallies,
160
+ * and it answers the same question — *what was in the window?* — but it is
161
+ * **not** the same kind of fact (0297). A page reading of two audiences is
162
+ * read as neither, because adding two forms' node counters is one number
163
+ * about two pages. A region map of two audiences is read whole, because
164
+ * adding two forms' arrivals is one number about one deployment's readers:
165
+ * they are people, and a person who arrived arrived once whichever form they
166
+ * were served.
167
+ *
168
+ * So more than one member here is a **measurement and never a fault**: *this
169
+ * map is a sum over two of the forms you serve*. `[]` is a window whose rows
170
+ * named none, which is every window written before the column existed (0284)
171
+ * and every one a test builds by hand.
172
+ *
173
+ * It is deliberately not a proof of which form the map is of.
174
+ * {@link RegionReading.audienceId} is that, and it stays `null` on a map read
175
+ * whole however few audiences the rows named (0294) — because an `aud_` is a
176
+ * name the host chose for a predicate Loom never sees, and `aud_everyone` is
177
+ * a name for *everybody*. One member means one name was on the rows, not that
178
+ * one population was behind them.
179
+ */
180
+ readonly audiences: readonly AudienceId[];
181
+ /** Buckets large enough to name, most-read first. */
182
+ readonly regions: readonly RegionBucket[];
183
+ /** What was too small to name, as a total that names nowhere. */
184
+ readonly withheld: {
185
+ readonly buckets: number;
186
+ readonly views: number;
187
+ };
188
+ /** Every view in the rows, named or withheld. A reading never loses one. */
189
+ readonly views: number;
190
+ };
191
+ export type RegionReadingOptions = {
192
+ /** Raised above {@link DEFAULT_REGION_FLOOR}; a smaller number is the default. */
193
+ readonly floor?: number;
194
+ };
195
+ /**
196
+ * Rows from the store, read as something a screen may show.
197
+ *
198
+ * **Grouped before it is suppressed, and the order matters.** Ten views of one
199
+ * revision and twenty of the next are thirty views of one country, which is a
200
+ * readership; suppressing each revision first would withhold both and report a
201
+ * map of nowhere. A caller asking about one revision filters at the store,
202
+ * where the filter belongs.
203
+ *
204
+ * **The unplaced bucket is never withheld**, however small it is. It names no
205
+ * place, so there is nobody in it to re-identify, and hiding it would mean a
206
+ * reading whose numbers do not add up to the number of views there were.
207
+ *
208
+ * **It sums across the audiences it was handed, and says which ones they
209
+ * were.** A page served in two forms counts each form's arrivals on its own row
210
+ * (0284), and both forms' readers are the same deployment's readers — a person
211
+ * who arrived arrived once, whichever form they were served — so a map of the
212
+ * window is the readership and not a collapse of two. The census is published
213
+ * on {@link RegionReading.audiences} so that a caller comparing two such maps
214
+ * can say what each was a sum over, and nothing is refused on it (0297).
215
+ */
216
+ export declare const regionReadingOf: (rows: readonly StoredRegionCount[], options?: RegionReadingOptions) => RegionReading;
217
+ /**
218
+ * One revision's region rows, read as a map, without the caller writing the
219
+ * filter.
220
+ *
221
+ * The same shape and the same reason as `pageViewsFor` in
222
+ * [`page-views.ts`](page-views.ts): the matching is the part of every join in
223
+ * this subsystem that fails quietly when it is got wrong, and a comparison of
224
+ * two revisions' readerships is the first thing here that has to do it twice in
225
+ * one call. Reading one revision's map against another revision's rows would
226
+ * answer confidently and be about nothing.
227
+ *
228
+ * **Filtered before it is floored, which is the half that is not obvious.**
229
+ * {@link regionReadingOf} groups across whatever it is handed, because thirty
230
+ * views of one country spread over two revisions are a readership and
231
+ * suppressing each revision first would withhold both. A caller asking about
232
+ * one revision is asking a narrower question and gets a narrower answer: the
233
+ * floor bites harder per revision than it does across a deployment, so a quiet
234
+ * page reports more of itself as withheld. That is the floor working rather
235
+ * than a fault, and it is why a readership comparison is answerable on a page
236
+ * with traffic and says so on a page without.
237
+ */
238
+ export type RegionReadingFor = {
239
+ /** The revision's own map, floored. */
240
+ readonly reading: RegionReading;
241
+ /**
242
+ * Rows for another tree or another revision, and ignored.
243
+ *
244
+ * Counting another revision's arrivals into this one's map is the mistake
245
+ * that would make a readership comparison compare a revision with itself.
246
+ */
247
+ readonly foreign: number;
248
+ /**
249
+ * Rows for this revision in another audience, and ignored.
250
+ *
251
+ * A page served in two forms counts each form's arrivals on its own row
252
+ * (0284), and both forms' readers are real readers of the page — so this is
253
+ * neither foreign nor a doubled bucket. It is the other form's readership,
254
+ * which is a different map and not part of this one: a mix taken over both
255
+ * is one composition of two populations, and a comparison beside it would be
256
+ * comparing neither form with itself.
257
+ */
258
+ readonly otherAudience: number;
259
+ /**
260
+ * Rows naming a region **and an audience** this revision already had a row
261
+ * for, beyond the first, every one of which was ignored.
262
+ *
263
+ * A store keeps one row per tree, revision, audience and region, so this
264
+ * cannot come out of one read — it happens when a caller concatenates two
265
+ * windows of rows, and the store's counts are already running totals rather
266
+ * than a window's. Adding them would double a bucket, which is the one error
267
+ * in this subsystem that cannot be undone afterwards (0158), so the first row
268
+ * stands and the fact is reported.
269
+ *
270
+ * **The audience is part of what makes two rows two rows**, and leaving it
271
+ * out was a quiet undercount (0297). A revision served in two forms (0263)
272
+ * has two rows for one country, one per form, and a map read whole of such a
273
+ * revision dropped the second as the first handed in twice: 60 views
274
+ * published where 460 arrived, with the loss reported as a count of
275
+ * duplicates nobody would read as an undercount. A form's own map is
276
+ * unaffected — the audience is picked before this, so region and audience key
277
+ * the same rows region alone did.
278
+ */
279
+ readonly duplicated: number;
280
+ };
281
+ /**
282
+ * Pick one revision's region rows out of a set of them and read them.
283
+ *
284
+ * Linear in the rows, with one pass and one map.
285
+ */
286
+ export declare const regionReadingFor: (where: RevisionOf, rows: readonly StoredRegionCount[], options?: RegionReadingOptions) => RegionReadingFor;
287
+ //# sourceMappingURL=region.d.ts.map
@@ -0,0 +1,198 @@
1
+ import { z } from "zod";
2
+ import { audiencesIn } from "./audiences.js";
3
+ /**
4
+ * Where readers are, as a counter and nothing else.
5
+ *
6
+ * A coarse region is the one fact about a reader that a deployment can know
7
+ * without the browser ever being told it is being measured: the request arrived
8
+ * from somewhere, and the platform in front of the application already wrote
9
+ * that down in a header. Nothing is added to a batch, nothing is asked of the
10
+ * page, and the address the region was read from is never stored.
11
+ *
12
+ * Three refusals hold the shape, and they are the design rather than caveats on
13
+ * it:
14
+ *
15
+ * - **It lands on a counter, never on a buffered batch.** A region beside a
16
+ * view key on a raw row is the beginning of a profile — one row saying *this
17
+ * page view came from here* — and the only thing stopping it becoming one
18
+ * would be that nobody got round to joining the two. So the region is counted
19
+ * at the door and the raw row never carries it.
20
+ * - **A bucket is reported only once it is too large to be a person.** A country
21
+ * with a handful of views in it is a reader, not a readership. The floor is a
22
+ * number this module owns, a deployment may raise it and may not lower it, and
23
+ * what it suppresses is still *counted* — a reading says how many views it is
24
+ * withholding, so the total stays true while the attribution does not exist.
25
+ * - **One page view is one view.** Counting deliveries instead would be the
26
+ * quiet failure: a reader who stays ten minutes posts a hundred batches, so a
27
+ * single person would clear any floor on their own and the protection would
28
+ * invert. A batch says whether it opened its page view, and only those count.
29
+ *
30
+ * The exactness is worth naming, because the per-node counters do not have it.
31
+ * `views` on a tally counts distinct page views inside a rollup window and is
32
+ * added to the next window's, so a view that straddles the boundary is counted
33
+ * twice (0147). A region view is counted once, at the moment a page view began,
34
+ * and is never recounted — so these numbers add across revisions, across trees
35
+ * and across months without drifting.
36
+ */
37
+ /** The sentinel, before it is a region. The schema below is what makes it one. */
38
+ const UNKNOWN = "unknown";
39
+ /**
40
+ * A region nobody can name.
41
+ *
42
+ * A deployment behind a proxy that adds no such header, a request from a
43
+ * development machine, a header holding something that is not a country code —
44
+ * all of them are this, and it is a bucket rather than a dropped row. *We do
45
+ * not know where 40 of these views came from* is a fact about the measurement;
46
+ * silently keeping only the views that could be placed is a figure that looks
47
+ * complete and is not.
48
+ *
49
+ * Seven characters, so it can never collide with a two-letter code.
50
+ */
51
+ export const UNKNOWN_REGION = UNKNOWN;
52
+ /** Two uppercase letters, which is what a country code is. */
53
+ export const regionPattern = /^[A-Z]{2}$/;
54
+ /**
55
+ * A country, or the admission that there is none.
56
+ *
57
+ * Deliberately no narrower. A subdivision or a city is the step from *where our
58
+ * readers are* to *who that reader was* — a city plus a count of two is a
59
+ * person with an address — and the header carrying one is sitting beside the
60
+ * header this reads. It is not read.
61
+ *
62
+ * Deliberately no wider either: the value becomes a column, and a column fed
63
+ * from a request header is a column a caller can write to. Two letters or the
64
+ * one sentinel is a closed set, so the worst a poisoned header can do is add to
65
+ * a bucket that already exists.
66
+ */
67
+ export const readerRegionSchema = z
68
+ .union([z.literal(UNKNOWN), z.string().regex(regionPattern)])
69
+ .brand();
70
+ /**
71
+ * Read a region off whatever the platform wrote, and never fail.
72
+ *
73
+ * Trimmed and upper-cased because headers are written by whoever is in front of
74
+ * the application and casing is not a thing to have an opinion about. Anything
75
+ * that is not a country code — absent, empty, a city, a word, the Tor marker
76
+ * some platforms send — is unplaced rather than refused: this runs on the
77
+ * request path of the one public write endpoint, and a region that cannot be
78
+ * read is a bucket, not an error.
79
+ */
80
+ export const readerRegionOf = (given) => {
81
+ if (given === null || given === undefined)
82
+ return UNKNOWN_REGION;
83
+ const code = given.trim().toUpperCase();
84
+ return regionPattern.test(code) ? code : UNKNOWN_REGION;
85
+ };
86
+ /**
87
+ * What one delivery adds, which is one view per page view it opened.
88
+ *
89
+ * **It is handed the openings rather than the delivery**, so that a region can
90
+ * only ever be a stamp on a page view somebody already counted. The walk that
91
+ * finds them, and the deduplication that makes a retried opening one arrival
92
+ * rather than two, is `openingsOf` in `page-views.ts` — shared deliberately,
93
+ * because two counters that each decided for themselves how many readers
94
+ * arrived would sooner or later disagree about it, and the disagreement would
95
+ * surface as a map whose numbers do not add up to the number of page views
96
+ * there were.
97
+ *
98
+ * A delivery that opened nothing adds nothing, and a sender that never says
99
+ * adds nothing at all — which is the honest answer for a batch synthesised on a
100
+ * server or replayed from a fixture, exactly as such a batch adds nothing to
101
+ * any view count.
102
+ */
103
+ export const regionCountsOf = (openings, region) => openings.map(({ treeId, revision, views }) => ({ treeId, revision, region, views }));
104
+ /**
105
+ * The smallest a bucket may be before it is named.
106
+ *
107
+ * Twenty-five, and the number is a judgement rather than a derivation: it is
108
+ * low enough that a deployment with a few hundred readers sees its own map, and
109
+ * high enough that no bucket is one person, one household or one office. A
110
+ * deployment that wants more caution raises it.
111
+ *
112
+ * It is not lowerable, and that is the one place this subsystem overrides an
113
+ * operator. The floor is what makes the aggregate an aggregate; a deployment
114
+ * that could set it to one would be running a different product, and the
115
+ * difference would be invisible on the screen that showed the result.
116
+ */
117
+ export const DEFAULT_REGION_FLOOR = 25;
118
+ /**
119
+ * The floor that will actually be used, given what somebody asked for.
120
+ *
121
+ * Raise-only, and anything that is not a whole number of views is the default —
122
+ * a floor read from configuration is read from a string somebody typed, and the
123
+ * direction to be wrong in is the cautious one.
124
+ */
125
+ export const regionFloorOf = (asked) => asked === undefined || !Number.isInteger(asked) ? DEFAULT_REGION_FLOOR : Math.max(DEFAULT_REGION_FLOOR, asked);
126
+ /**
127
+ * Rows from the store, read as something a screen may show.
128
+ *
129
+ * **Grouped before it is suppressed, and the order matters.** Ten views of one
130
+ * revision and twenty of the next are thirty views of one country, which is a
131
+ * readership; suppressing each revision first would withhold both and report a
132
+ * map of nowhere. A caller asking about one revision filters at the store,
133
+ * where the filter belongs.
134
+ *
135
+ * **The unplaced bucket is never withheld**, however small it is. It names no
136
+ * place, so there is nobody in it to re-identify, and hiding it would mean a
137
+ * reading whose numbers do not add up to the number of views there were.
138
+ *
139
+ * **It sums across the audiences it was handed, and says which ones they
140
+ * were.** A page served in two forms counts each form's arrivals on its own row
141
+ * (0284), and both forms' readers are the same deployment's readers — a person
142
+ * who arrived arrived once, whichever form they were served — so a map of the
143
+ * window is the readership and not a collapse of two. The census is published
144
+ * on {@link RegionReading.audiences} so that a caller comparing two such maps
145
+ * can say what each was a sum over, and nothing is refused on it (0297).
146
+ */
147
+ export const regionReadingOf = (rows, options = {}) => {
148
+ const floor = regionFloorOf(options.floor);
149
+ const grouped = new Map();
150
+ for (const row of rows) {
151
+ grouped.set(row.region, (grouped.get(row.region) ?? 0) + row.views);
152
+ }
153
+ const buckets = [...grouped.entries()].map(([region, views]) => ({ region, views }));
154
+ const nameable = (bucket) => bucket.region === UNKNOWN_REGION || bucket.views >= floor;
155
+ const named = buckets.filter(nameable);
156
+ const small = buckets.filter((bucket) => !nameable(bucket));
157
+ return {
158
+ floor,
159
+ audienceId: null,
160
+ audiences: audiencesIn(rows),
161
+ /** Most-read first, and by code when two are equal, so a screen does not reorder on a refresh. */
162
+ regions: named.sort((one, other) => other.views - one.views || one.region.localeCompare(other.region)),
163
+ withheld: {
164
+ buckets: small.length,
165
+ views: small.reduce((total, bucket) => total + bucket.views, 0),
166
+ },
167
+ views: buckets.reduce((total, bucket) => total + bucket.views, 0),
168
+ };
169
+ };
170
+ /**
171
+ * Pick one revision's region rows out of a set of them and read them.
172
+ *
173
+ * Linear in the rows, with one pass and one map.
174
+ */
175
+ export const regionReadingFor = (where, rows, options = {}) => {
176
+ const here = rows.filter((row) => row.treeId === where.treeId && row.revision === where.revision);
177
+ const audience = where.audienceId ?? null;
178
+ const matching = audience === null ? here : here.filter((row) => row.audienceId === audience);
179
+ /**
180
+ * Keyed by the region **and** the audience, which is what the store keeps one
181
+ * row per (0284): two forms' arrivals in one country are two rows and one
182
+ * readership, and keying by the region alone dropped the second as a repeat
183
+ * of the first (0297).
184
+ */
185
+ const first = new Map();
186
+ for (const row of matching) {
187
+ const bucket = `${row.region}\u0000${row.audienceId}`;
188
+ if (!first.has(bucket))
189
+ first.set(bucket, row);
190
+ }
191
+ return {
192
+ reading: { ...regionReadingOf([...first.values()], options), audienceId: audience },
193
+ foreign: rows.length - here.length,
194
+ otherAudience: here.length - matching.length,
195
+ duplicated: matching.length - first.size,
196
+ };
197
+ };
198
+ //# sourceMappingURL=region.js.map
@@ -0,0 +1,141 @@
1
+ import type { CollectionOutcome } from "./collect.js";
2
+ import type { DeliveryRetention } from "./notice.js";
3
+ /**
4
+ * Whether the deployment keeps the retention ceiling it publishes to its
5
+ * readers.
6
+ *
7
+ * A notice tells the reader two things about a delivery's life: the age it
8
+ * ripens at, which is this framework's own number, and how often the deployment
9
+ * sweeps the ripe ones away, which is a claim about a cron nobody here can see
10
+ * (0320). The two add to a ceiling — *gone within 70 minutes of arriving* — and
11
+ * a deployment that states ten minutes and sweeps weekly publishes that
12
+ * sentence to every reader of its privacy page with nothing behind it.
13
+ *
14
+ * **The evidence is already in the sweep's own hands.** A run scans the buffer
15
+ * from its oldest end, so the age of the oldest delivery still waiting is a
16
+ * number every run has and none of them reported. If that age is past the
17
+ * ceiling, then a delivery existed that readers were told was gone — and it
18
+ * existed for however long the gap is, whatever this run then deletes.
19
+ *
20
+ * So the check costs no read, no column, no byte on any wire and nothing in a
21
+ * browser: it is a subtraction over what a sweep already looked at.
22
+ *
23
+ * ## It is beside the notice and never inside it
24
+ *
25
+ * `collectionNoticeOf` is a pure function of a deployment's configuration and
26
+ * has to stay one (0313): a privacy page with a store and a clock behind it is
27
+ * a page that cannot render while the database is down, which is worse for a
28
+ * reader than a stated ceiling. The judgement therefore lives here, where a
29
+ * store and a clock are already in the room, and it is handed the same
30
+ * retention the notice publishes rather than a second derivation of it — a
31
+ * sweep that computed its own ceiling could clear a promise nobody made.
32
+ *
33
+ * ## What it refuses to judge
34
+ *
35
+ * Three of the five states answer *nothing is wrong* without asserting that
36
+ * anything is right, and each is a refusal rather than a gap: a deployment that
37
+ * stated no interval published no ceiling, a run that never reached the buffer
38
+ * saw no delivery, and a run that found nothing ripe has proved the promise
39
+ * holds without needing a figure at all.
40
+ *
41
+ * Pure, constant-time, and reaches no store, clock or DOM.
42
+ */
43
+ /** How a published retention ceiling stood at the moment of one sweep. */
44
+ export type RetentionPromise =
45
+ /**
46
+ * The deployment stated no sweep interval, so its notice publishes no
47
+ * ceiling.
48
+ *
49
+ * There is nothing for a run to keep or break. The remedy is not a sweep's:
50
+ * an operator states the interval their cron actually runs on, and until they
51
+ * do their readers are told when a delivery ripens and nothing about when it
52
+ * goes.
53
+ */
54
+ {
55
+ readonly state: "unpromised";
56
+ }
57
+ /**
58
+ * The run read no delivery, so nothing here says how old the oldest one is.
59
+ *
60
+ * Either it never reached the buffer — refused on its window, or the store
61
+ * was unavailable — or the one instant it needed could not be read. A buffer
62
+ * the sweep cannot see is a promise nothing can speak for, and the honest
63
+ * answer is silence rather than *kept*.
64
+ */
65
+ | {
66
+ readonly state: "unread";
67
+ }
68
+ /**
69
+ * Nothing in the buffer is old enough to count, so nothing in it can be past
70
+ * the ceiling.
71
+ *
72
+ * The strongest of the three quiet answers and the only one that is a proof.
73
+ * A scan runs from the oldest end, so a run that found nothing ripe found
74
+ * every delivery younger than the ripeness window — and the ceiling is that
75
+ * window plus a sweep, which is longer. An empty buffer lands here too, for
76
+ * the same reason and with nothing waiting.
77
+ */
78
+ | {
79
+ readonly state: "unripe";
80
+ }
81
+ /**
82
+ * The oldest delivery in the buffer is within the ceiling the notice
83
+ * publishes.
84
+ *
85
+ * Both figures travel, because the sentence an operator wants is the
86
+ * comparison and not the verdict: *the oldest here is twelve minutes old and
87
+ * your readers are told seventy*.
88
+ */
89
+ | {
90
+ readonly state: "kept";
91
+ /** How old the oldest delivery still in the buffer was, in milliseconds. */
92
+ readonly oldestMs: number;
93
+ /** The ceiling the notice publishes: the ripeness window plus one sweep. */
94
+ readonly goneWithinMs: number;
95
+ }
96
+ /**
97
+ * A delivery is older than the ceiling the notice publishes, so that sentence
98
+ * is false and was false for `byMs` before this run.
99
+ *
100
+ * The deployment is either sweeping less often than it stated or not sweeping
101
+ * at all, and the two are the same fault from here. Raising the stated
102
+ * interval makes the published promise true and weaker; sweeping on the
103
+ * interval already stated makes it true and keeps it — and that choice is an
104
+ * operator's, so this names the gap rather than a remedy.
105
+ */
106
+ | {
107
+ readonly state: "broken";
108
+ readonly oldestMs: number;
109
+ readonly goneWithinMs: number;
110
+ /** How far past the ceiling the oldest delivery is. */
111
+ readonly byMs: number;
112
+ };
113
+ /**
114
+ * Judge one sweep's own evidence against the ceiling its deployment publishes.
115
+ *
116
+ * The retention is taken whole — the same `Pick` of the notice the reader's
117
+ * sentence is built from (0320) — so the ceiling judged here is the ceiling
118
+ * published, by construction rather than by a reviewer.
119
+ *
120
+ * **An unstated interval wins over everything else**, including a buffer months
121
+ * behind. It is not that the buffer is fine; it is that no ceiling was
122
+ * published, so a run has no claim of its deployment's to measure. The operator
123
+ * hears about an unstated schedule from the setting, which is where the remedy
124
+ * is.
125
+ *
126
+ * **A delivery received in the future is kept, by the same subtraction rather
127
+ * than by a special case** — a negative age is never longer than a positive
128
+ * ceiling, which is how the stall check answers a clock that disagrees with
129
+ * itself (0274).
130
+ */
131
+ export declare const retentionPromiseOf: (outcome: CollectionOutcome, retention: DeliveryRetention) => RetentionPromise;
132
+ /**
133
+ * One line for the operator who runs the sweep, because they are the only
134
+ * person who can close the gap.
135
+ *
136
+ * Milliseconds, as the settings an operator typed are in: a line that rounded
137
+ * to minutes would not tell somebody who wrote an interval in the wrong units
138
+ * which units it wanted.
139
+ */
140
+ export declare const describeRetentionPromise: (promise: RetentionPromise) => string;
141
+ //# sourceMappingURL=retention.d.ts.map