@jam-overture/loom 0.1.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 (414) 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/audience/compose.d.ts +112 -0
  11. package/dist/audience/compose.js +134 -0
  12. package/dist/audience/memory.d.ts +14 -0
  13. package/dist/audience/memory.js +71 -0
  14. package/dist/audience/overlay-store.d.ts +343 -0
  15. package/dist/audience/overlay-store.js +217 -0
  16. package/dist/audience/rule.d.ts +121 -0
  17. package/dist/audience/rule.js +78 -0
  18. package/dist/cli/index.d.ts +3 -4
  19. package/dist/cli/index.js +3 -4
  20. package/dist/cli/templates.js +19 -0
  21. package/dist/data/adapter.d.ts +9 -1
  22. package/dist/data/adapter.js +2 -0
  23. package/dist/data/plan.js +0 -0
  24. package/dist/data/resolution.d.ts +23 -1
  25. package/dist/data/resolve.d.ts +31 -4
  26. package/dist/data/resolve.js +11 -3
  27. package/dist/ids.d.ts +10 -0
  28. package/dist/ids.js +11 -1
  29. package/dist/index.d.ts +1 -0
  30. package/dist/index.js +1 -0
  31. package/dist/interpretation/anthropic.d.ts +1 -1
  32. package/dist/interpretation/anthropic.js +2 -22
  33. package/dist/interpretation/client.d.ts +1 -1
  34. package/dist/interpretation/materialize.js +67 -22
  35. package/dist/interpretation/openai-compatible.d.ts +36 -0
  36. package/dist/interpretation/openai-compatible.js +79 -0
  37. package/dist/interpretation/status.d.ts +19 -0
  38. package/dist/interpretation/status.js +26 -0
  39. package/dist/live/index.d.ts +73 -0
  40. package/dist/live/index.js +73 -0
  41. package/dist/live/pages.d.ts +187 -0
  42. package/dist/live/pages.js +161 -0
  43. package/dist/live/pull.d.ts +147 -0
  44. package/dist/live/pull.js +398 -0
  45. package/dist/live/pulling.d.ts +79 -0
  46. package/dist/live/pulling.js +117 -0
  47. package/dist/live/window.d.ts +129 -0
  48. package/dist/live/window.js +132 -0
  49. package/dist/patch.d.ts +54 -0
  50. package/dist/patch.js +44 -0
  51. package/dist/project/closing.d.ts +51 -0
  52. package/dist/project/closing.js +53 -0
  53. package/dist/project/memory.d.ts +20 -0
  54. package/dist/project/memory.js +97 -0
  55. package/dist/project/project.d.ts +90 -0
  56. package/dist/project/project.js +91 -0
  57. package/dist/project/store.d.ts +135 -0
  58. package/dist/project/store.js +41 -0
  59. package/dist/registered.d.ts +64 -0
  60. package/dist/registered.js +118 -0
  61. package/dist/render/addressed.d.ts +35 -0
  62. package/dist/render/addressed.js +79 -0
  63. package/dist/render/behaviour-adjust.d.ts +11 -19
  64. package/dist/render/behaviour-adjust.js +75 -21
  65. package/dist/render/behaviour-present.d.ts +8 -0
  66. package/dist/render/behaviour-present.js +57 -6
  67. package/dist/render/behaviour.d.ts +98 -17
  68. package/dist/render/behaviour.js +91 -26
  69. package/dist/render/control-name.d.ts +68 -0
  70. package/dist/render/control-name.js +37 -0
  71. package/dist/render/diagnostics.d.ts +72 -0
  72. package/dist/render/diagnostics.js +7 -0
  73. package/dist/render/document-theme.d.ts +70 -0
  74. package/dist/render/document-theme.js +139 -0
  75. package/dist/render/editable.d.ts +15 -1
  76. package/dist/render/editable.js +13 -1
  77. package/dist/render/expected.d.ts +98 -0
  78. package/dist/render/expected.js +88 -0
  79. package/dist/render/index.d.ts +4 -0
  80. package/dist/render/index.js +4 -0
  81. package/dist/render/reads.d.ts +11 -0
  82. package/dist/render/reads.js +12 -1
  83. package/dist/render/render.d.ts +11 -0
  84. package/dist/render/render.js +294 -53
  85. package/dist/render/request.d.ts +8 -1
  86. package/dist/render/request.js +1 -0
  87. package/dist/render/slots.d.ts +52 -0
  88. package/dist/render/slots.js +24 -0
  89. package/dist/render/theme.d.ts +54 -1
  90. package/dist/render/theme.js +23 -1
  91. package/dist/render/unshown.d.ts +152 -0
  92. package/dist/render/unshown.js +80 -0
  93. package/dist/runtime/analysis.d.ts +94 -9
  94. package/dist/runtime/analysis.js +54 -9
  95. package/dist/runtime/assessment.d.ts +36 -2
  96. package/dist/runtime/assessment.js +27 -2
  97. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  98. package/dist/runtime/auto-apply-ceiling.js +66 -0
  99. package/dist/runtime/checks.d.ts +148 -0
  100. package/dist/runtime/checks.js +112 -0
  101. package/dist/runtime/disposition.d.ts +96 -0
  102. package/dist/runtime/disposition.js +46 -0
  103. package/dist/runtime/gate.js +91 -10
  104. package/dist/runtime/index.d.ts +4 -0
  105. package/dist/runtime/index.js +4 -0
  106. package/dist/runtime/irreversibility.d.ts +64 -0
  107. package/dist/runtime/irreversibility.js +45 -0
  108. package/dist/runtime/nesting.d.ts +13 -1
  109. package/dist/runtime/nesting.js +41 -24
  110. package/dist/runtime/pipeline.d.ts +43 -0
  111. package/dist/runtime/pipeline.js +10 -2
  112. package/dist/runtime/policy-change.d.ts +93 -0
  113. package/dist/runtime/policy-change.js +305 -0
  114. package/dist/runtime/policy-log.d.ts +406 -0
  115. package/dist/runtime/policy-log.js +285 -0
  116. package/dist/runtime/policy.d.ts +8 -6
  117. package/dist/runtime/policy.js +5 -2
  118. package/dist/runtime/repointing.js +0 -0
  119. package/dist/runtime/reversibility.d.ts +11 -9
  120. package/dist/runtime/stakes.d.ts +129 -1
  121. package/dist/runtime/stakes.js +240 -26
  122. package/dist/runtime/vocabulary.d.ts +164 -7
  123. package/dist/runtime/vocabulary.js +181 -8
  124. package/dist/sdk/audit.d.ts +174 -3
  125. package/dist/sdk/audit.js +176 -17
  126. package/dist/sdk/catalogue.d.ts +9 -1
  127. package/dist/sdk/conformance.d.ts +37 -3
  128. package/dist/sdk/conformance.js +25 -4
  129. package/dist/sdk/definition.d.ts +129 -5
  130. package/dist/sdk/definition.js +66 -0
  131. package/dist/sdk/registry.d.ts +45 -2
  132. package/dist/sdk/registry.js +102 -1
  133. package/dist/signals/acted.contract.d.ts +21 -0
  134. package/dist/signals/acted.contract.js +236 -0
  135. package/dist/signals/acted.d.ts +359 -0
  136. package/dist/signals/acted.js +135 -0
  137. package/dist/signals/action-change.d.ts +507 -0
  138. package/dist/signals/action-change.js +265 -0
  139. package/dist/signals/action.d.ts +331 -0
  140. package/dist/signals/action.js +182 -0
  141. package/dist/signals/agenda.d.ts +585 -0
  142. package/dist/signals/agenda.js +295 -0
  143. package/dist/signals/applied-window.contract.d.ts +23 -0
  144. package/dist/signals/applied-window.contract.js +160 -0
  145. package/dist/signals/arrivals.contract.d.ts +21 -0
  146. package/dist/signals/arrivals.contract.js +180 -0
  147. package/dist/signals/arrivals.d.ts +375 -0
  148. package/dist/signals/arrivals.js +254 -0
  149. package/dist/signals/arriving.d.ts +210 -0
  150. package/dist/signals/arriving.js +133 -0
  151. package/dist/signals/audiences.d.ts +528 -0
  152. package/dist/signals/audiences.js +255 -0
  153. package/dist/signals/broadcast.d.ts +33 -17
  154. package/dist/signals/broadcast.js +255 -32
  155. package/dist/signals/change.d.ts +378 -0
  156. package/dist/signals/change.js +327 -0
  157. package/dist/signals/collect.d.ts +169 -34
  158. package/dist/signals/collect.js +186 -38
  159. package/dist/signals/conversion.d.ts +348 -0
  160. package/dist/signals/conversion.js +235 -0
  161. package/dist/signals/copy-change.d.ts +553 -0
  162. package/dist/signals/copy-change.js +377 -0
  163. package/dist/signals/copy.d.ts +337 -0
  164. package/dist/signals/copy.js +211 -0
  165. package/dist/signals/correlated.contract.d.ts +24 -0
  166. package/dist/signals/correlated.contract.js +94 -0
  167. package/dist/signals/counters.d.ts +97 -0
  168. package/dist/signals/counters.js +160 -0
  169. package/dist/signals/deliver.d.ts +23 -4
  170. package/dist/signals/deliver.js +34 -6
  171. package/dist/signals/deployment-change.d.ts +395 -0
  172. package/dist/signals/deployment-change.js +309 -0
  173. package/dist/signals/deployment.d.ts +278 -0
  174. package/dist/signals/deployment.js +178 -0
  175. package/dist/signals/door.d.ts +114 -0
  176. package/dist/signals/door.js +77 -0
  177. package/dist/signals/expire.d.ts +192 -0
  178. package/dist/signals/expire.js +213 -0
  179. package/dist/signals/fold.d.ts +10 -0
  180. package/dist/signals/fold.js +5 -1
  181. package/dist/signals/form-action.d.ts +302 -0
  182. package/dist/signals/form-action.js +169 -0
  183. package/dist/signals/form-copy.d.ts +523 -0
  184. package/dist/signals/form-copy.js +346 -0
  185. package/dist/signals/forms.d.ts +247 -0
  186. package/dist/signals/forms.js +147 -0
  187. package/dist/signals/frontier.d.ts +268 -0
  188. package/dist/signals/frontier.js +145 -0
  189. package/dist/signals/funnel-change.d.ts +548 -0
  190. package/dist/signals/funnel-change.js +361 -0
  191. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  192. package/dist/signals/funnel-hours.contract.js +221 -0
  193. package/dist/signals/funnel-hours.d.ts +293 -0
  194. package/dist/signals/funnel-hours.js +99 -0
  195. package/dist/signals/funnel.d.ts +592 -0
  196. package/dist/signals/funnel.js +231 -0
  197. package/dist/signals/health.d.ts +694 -0
  198. package/dist/signals/health.js +573 -0
  199. package/dist/signals/index.d.ts +60 -0
  200. package/dist/signals/index.js +60 -0
  201. package/dist/signals/ingest.d.ts +56 -1
  202. package/dist/signals/ingest.js +91 -1
  203. package/dist/signals/inside.d.ts +190 -0
  204. package/dist/signals/inside.js +263 -0
  205. package/dist/signals/join.d.ts +56 -0
  206. package/dist/signals/join.js +60 -0
  207. package/dist/signals/journal.d.ts +123 -9
  208. package/dist/signals/kept.contract.d.ts +22 -0
  209. package/dist/signals/kept.contract.js +111 -0
  210. package/dist/signals/kinds.d.ts +8 -6
  211. package/dist/signals/kinds.js +14 -6
  212. package/dist/signals/library-action.d.ts +430 -0
  213. package/dist/signals/library-action.js +336 -0
  214. package/dist/signals/library-agenda-change.d.ts +324 -0
  215. package/dist/signals/library-agenda-change.js +199 -0
  216. package/dist/signals/library-agenda.d.ts +258 -0
  217. package/dist/signals/library-agenda.js +167 -0
  218. package/dist/signals/library-change.d.ts +477 -0
  219. package/dist/signals/library-change.js +335 -0
  220. package/dist/signals/library-copy-change.d.ts +498 -0
  221. package/dist/signals/library-copy-change.js +476 -0
  222. package/dist/signals/library-pace.d.ts +319 -0
  223. package/dist/signals/library-pace.js +305 -0
  224. package/dist/signals/library-reach-change.d.ts +646 -0
  225. package/dist/signals/library-reach-change.js +542 -0
  226. package/dist/signals/library-reach.d.ts +377 -0
  227. package/dist/signals/library-reach.js +227 -0
  228. package/dist/signals/library-senders-change.d.ts +457 -0
  229. package/dist/signals/library-senders-change.js +367 -0
  230. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  231. package/dist/signals/library-senders-reach-change.js +538 -0
  232. package/dist/signals/library-senders-reach.d.ts +340 -0
  233. package/dist/signals/library-senders-reach.js +252 -0
  234. package/dist/signals/library-senders.d.ts +271 -0
  235. package/dist/signals/library-senders.js +180 -0
  236. package/dist/signals/library-word-reach-change.d.ts +567 -0
  237. package/dist/signals/library-word-reach-change.js +564 -0
  238. package/dist/signals/library.d.ts +306 -0
  239. package/dist/signals/library.js +178 -0
  240. package/dist/signals/memory.d.ts +9 -0
  241. package/dist/signals/memory.js +246 -14
  242. package/dist/signals/migrate.d.ts +20 -4
  243. package/dist/signals/migrate.js +269 -8
  244. package/dist/signals/notice.d.ts +389 -0
  245. package/dist/signals/notice.js +250 -0
  246. package/dist/signals/pace-change.d.ts +501 -0
  247. package/dist/signals/pace-change.js +310 -0
  248. package/dist/signals/pace.d.ts +296 -0
  249. package/dist/signals/pace.js +291 -0
  250. package/dist/signals/page-views.d.ts +365 -0
  251. package/dist/signals/page-views.js +218 -0
  252. package/dist/signals/part-pace.d.ts +378 -0
  253. package/dist/signals/part-pace.js +333 -0
  254. package/dist/signals/parts.d.ts +354 -0
  255. package/dist/signals/parts.js +232 -0
  256. package/dist/signals/postgres.d.ts +16 -2
  257. package/dist/signals/postgres.js +753 -76
  258. package/dist/signals/progress.d.ts +212 -0
  259. package/dist/signals/progress.js +150 -0
  260. package/dist/signals/ratios.d.ts +108 -0
  261. package/dist/signals/ratios.js +40 -0
  262. package/dist/signals/reach.d.ts +309 -0
  263. package/dist/signals/reach.js +93 -0
  264. package/dist/signals/readable.d.ts +34 -0
  265. package/dist/signals/readable.js +34 -0
  266. package/dist/signals/readership.d.ts +381 -0
  267. package/dist/signals/readership.js +308 -0
  268. package/dist/signals/region-pages.d.ts +173 -0
  269. package/dist/signals/region-pages.js +62 -0
  270. package/dist/signals/region.d.ts +287 -0
  271. package/dist/signals/region.js +198 -0
  272. package/dist/signals/retention.d.ts +163 -0
  273. package/dist/signals/retention.js +75 -0
  274. package/dist/signals/rhythm.d.ts +302 -0
  275. package/dist/signals/rhythm.js +262 -0
  276. package/dist/signals/rollup.d.ts +194 -4
  277. package/dist/signals/rollup.js +0 -0
  278. package/dist/signals/schema.d.ts +1069 -1
  279. package/dist/signals/schema.js +393 -3
  280. package/dist/signals/signal.d.ts +237 -11
  281. package/dist/signals/signal.js +70 -10
  282. package/dist/signals/silence-census.d.ts +205 -0
  283. package/dist/signals/silence-census.js +87 -0
  284. package/dist/signals/silences.d.ts +1147 -0
  285. package/dist/signals/silences.js +996 -0
  286. package/dist/signals/subtrees.d.ts +123 -0
  287. package/dist/signals/subtrees.js +102 -0
  288. package/dist/signals/tally.d.ts +262 -12
  289. package/dist/signals/unread.d.ts +292 -0
  290. package/dist/signals/unread.js +137 -0
  291. package/dist/signals/window-agenda.d.ts +276 -0
  292. package/dist/signals/window-agenda.js +83 -0
  293. package/dist/signals/window-figures.d.ts +148 -0
  294. package/dist/signals/window-figures.js +42 -0
  295. package/dist/signals/window-funnels.d.ts +88 -0
  296. package/dist/signals/window-funnels.js +47 -0
  297. package/dist/signals/window.d.ts +866 -0
  298. package/dist/signals/window.js +693 -0
  299. package/dist/signals/words.d.ts +24 -0
  300. package/dist/signals/words.js +24 -0
  301. package/dist/store/cache.d.ts +101 -0
  302. package/dist/store/cache.js +149 -0
  303. package/dist/store/history.d.ts +82 -0
  304. package/dist/store/history.js +36 -0
  305. package/dist/store/index.d.ts +30 -0
  306. package/dist/store/index.js +30 -0
  307. package/dist/store/memory.d.ts +2 -1
  308. package/dist/store/memory.js +48 -12
  309. package/dist/store/migrate.d.ts +106 -0
  310. package/dist/store/migrate.js +323 -7
  311. package/dist/store/postgres-applications.d.ts +4 -0
  312. package/dist/store/postgres-applications.js +197 -0
  313. package/dist/store/postgres-audience.d.ts +14 -0
  314. package/dist/store/postgres-audience.js +272 -0
  315. package/dist/store/postgres-holds.d.ts +10 -1
  316. package/dist/store/postgres-holds.js +116 -101
  317. package/dist/store/postgres-policy-log.d.ts +14 -0
  318. package/dist/store/postgres-policy-log.js +240 -0
  319. package/dist/store/postgres-projects.d.ts +4 -0
  320. package/dist/store/postgres-projects.js +217 -0
  321. package/dist/store/postgres.d.ts +17 -1
  322. package/dist/store/postgres.js +60 -9
  323. package/dist/store/replay.d.ts +102 -1
  324. package/dist/store/replay.js +190 -19
  325. package/dist/store/reseed.d.ts +238 -0
  326. package/dist/store/reseed.js +308 -0
  327. package/dist/store/schema.d.ts +762 -2
  328. package/dist/store/schema.js +218 -5
  329. package/dist/store/source.d.ts +57 -1
  330. package/dist/store/source.js +65 -1
  331. package/dist/store/store.d.ts +29 -6
  332. package/dist/submit/resolve.d.ts +1 -1
  333. package/dist/submit/resolve.js +2 -1
  334. package/dist/telemetry/calibration.d.ts +25 -0
  335. package/dist/telemetry/calibration.js +27 -1
  336. package/dist/telemetry/event.d.ts +391 -33
  337. package/dist/telemetry/event.js +84 -20
  338. package/dist/telemetry/index.d.ts +2 -0
  339. package/dist/telemetry/index.js +2 -0
  340. package/dist/telemetry/journal.d.ts +104 -3
  341. package/dist/telemetry/journal.js +9 -0
  342. package/dist/telemetry/lookup.d.ts +27 -0
  343. package/dist/telemetry/lookup.js +18 -0
  344. package/dist/telemetry/memory.js +33 -1
  345. package/dist/telemetry/migrate.js +22 -1
  346. package/dist/telemetry/postgres.d.ts +10 -1
  347. package/dist/telemetry/postgres.js +188 -90
  348. package/dist/telemetry/remeasure.d.ts +78 -0
  349. package/dist/telemetry/remeasure.js +83 -0
  350. package/dist/telemetry/retention.d.ts +2 -2
  351. package/dist/telemetry/schema.d.ts +17 -0
  352. package/dist/telemetry/schema.js +27 -1
  353. package/dist/telemetry/sink.d.ts +2 -2
  354. package/dist/telemetry/window.d.ts +135 -0
  355. package/dist/telemetry/window.js +101 -0
  356. package/dist/testing/application-contract.d.ts +14 -0
  357. package/dist/testing/application-contract.js +270 -0
  358. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  359. package/dist/testing/audience-overlay-contract.js +354 -0
  360. package/dist/testing/contracts.d.ts +13 -7
  361. package/dist/testing/contracts.js +13 -7
  362. package/dist/testing/definitions.d.ts +78 -0
  363. package/dist/testing/definitions.js +134 -9
  364. package/dist/testing/doubles.d.ts +103 -0
  365. package/dist/testing/doubles.js +143 -0
  366. package/dist/testing/index.d.ts +2 -2
  367. package/dist/testing/index.js +2 -2
  368. package/dist/testing/journal-contract.js +297 -6
  369. package/dist/testing/model-contract.d.ts +110 -0
  370. package/dist/testing/model-contract.js +150 -0
  371. package/dist/testing/policy-log-contract.d.ts +26 -0
  372. package/dist/testing/policy-log-contract.js +344 -0
  373. package/dist/testing/project-contract.d.ts +14 -0
  374. package/dist/testing/project-contract.js +266 -0
  375. package/dist/testing/reader-signal-contract.d.ts +27 -2
  376. package/dist/testing/reader-signal-contract.js +475 -5
  377. package/dist/testing/store-contract.d.ts +7 -1
  378. package/dist/testing/store-contract.js +84 -3
  379. package/dist/theme/apply.d.ts +20 -1
  380. package/dist/theme/apply.js +5 -3
  381. package/dist/theme/contrast.d.ts +19 -14
  382. package/dist/theme/contrast.js +181 -17
  383. package/dist/theme/derive.d.ts +22 -0
  384. package/dist/theme/derive.js +54 -1
  385. package/dist/theme/library.js +1 -1
  386. package/dist/theme/measure.d.ts +34 -0
  387. package/dist/theme/measure.js +30 -1
  388. package/dist/theme/palettes.js +7 -7
  389. package/dist/theme/ramp.d.ts +64 -0
  390. package/dist/theme/ramp.js +114 -0
  391. package/dist/theme/registry.d.ts +9 -0
  392. package/dist/theme/registry.js +11 -1
  393. package/dist/theme/separation.d.ts +97 -3
  394. package/dist/theme/separation.js +75 -0
  395. package/dist/tree/apply.js +13 -0
  396. package/dist/tree/compare.d.ts +9 -0
  397. package/dist/tree/compare.js +18 -0
  398. package/dist/tree/mutation.d.ts +18 -0
  399. package/dist/tree/mutation.js +24 -12
  400. package/dist/tree/navigation.d.ts +5 -0
  401. package/dist/tree/navigation.js +32 -10
  402. package/dist/tree/outline.d.ts +7 -0
  403. package/dist/tree/outline.js +9 -5
  404. package/dist/write/computed.d.ts +60 -0
  405. package/dist/write/computed.js +61 -0
  406. package/dist/write/held.d.ts +59 -0
  407. package/dist/write/index.d.ts +5 -2
  408. package/dist/write/index.js +5 -2
  409. package/dist/write/reseed.d.ts +151 -0
  410. package/dist/write/reseed.js +184 -0
  411. package/dist/write/revert.js +2 -16
  412. package/package.json +25 -3
  413. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  414. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,389 @@
1
+ import type { ReaderSignalOptions } from "./broadcast.js";
2
+ import { type ReaderSignal, type ReaderSignalBatch, type ReaderSignalKind } from "./signal.js";
3
+ /**
4
+ * What a published page reports, written for the people it reports about.
5
+ *
6
+ * Every other reading in this subsystem answers a deployment's question. This
7
+ * is the one that answers a reader's, and it is the half of the argument that
8
+ * had nothing behind it: Loom exists so that a change to a page can be
9
+ * inspected, attributed and undone, and reader measurement that could not be
10
+ * explained to the person being measured would contradict the whole premise.
11
+ * Every competitor in this space collects more and explains less; the
12
+ * explaining has to be something a deployment can publish, not a paragraph in
13
+ * this repository.
14
+ *
15
+ * So this is a value rather than a page: a structure a deployment's privacy
16
+ * page, portal or consent surface can print, derived from the configuration its
17
+ * own pages are broadcast with.
18
+ *
19
+ * ## Why it is derived and not written
20
+ *
21
+ * A hand-written list of what a product collects is right on the day it is
22
+ * written. This one cannot drift from the payload, and it is the type system
23
+ * that holds it rather than a reviewer: {@link DELIVERY_FIELDS} and
24
+ * {@link SIGNAL_FIELDS} are keyed by the schema's own fields through
25
+ * `keyof Required<…>`, so **a field added to a batch without a sentence here
26
+ * does not compile.** `notice.test.ts` holds the other end, which a type cannot
27
+ * reach: it drives the real broadcaster over a real page and fails if a kind or
28
+ * a field arrives that this does not name.
29
+ *
30
+ * ## It is a ceiling, and never an understatement
31
+ *
32
+ * The notice names everything the configuration permits. A deployment that
33
+ * narrows `types` collects about fewer parts than this says, and one that turns
34
+ * `within` off carries no ancestry on the three delegated kinds. Both are
35
+ * published here as though they were on.
36
+ *
37
+ * That is deliberate in one direction only. A disclosure that overstates costs
38
+ * a reader nothing and a deployment a little credit; one that understates is
39
+ * the failure this module exists to make impossible. It also keeps the notice
40
+ * stable: a ceiling changes when the vocabulary or the deployment's own three
41
+ * numbers change, where a floor would have to be republished every time
42
+ * somebody added a primitive type to a list.
43
+ *
44
+ * ## What it is not
45
+ *
46
+ * **Not a consent gate and not a banner.** There is nothing here to consent to:
47
+ * a signal is anonymous and node-shaped, correlation is scoped to one page view
48
+ * by a key that never persists, and neither is configurable
49
+ * ([0146](../../decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md)).
50
+ * A notice says what is collected; the rules say it cannot be about a person.
51
+ * Per-reader identity is parked, and nothing here assumes it ever arrives or
52
+ * builds toward it — what a gate would need is a recorded decision, which is a
53
+ * different artefact from this one.
54
+ *
55
+ * **Not a reading.** It touches no store, no clock and no counter. Three
56
+ * numbers come from the deployment's own configuration — the window a
57
+ * delivery ripens at, the floor under a published country, and how often its
58
+ * sweep runs (0320) — and everything else is the vocabulary.
59
+ *
60
+ * ## The voice
61
+ *
62
+ * Every sentence in this module is addressed to a reader of the page, because
63
+ * that is who ends up reading them: *your address is never stored*, not *the
64
+ * reader's address is never stored*. It is the one module in `src/signals/`
65
+ * that speaks to anybody.
66
+ */
67
+ /** What one field of a delivery is about. */
68
+ export type FieldSubject =
69
+ /** The part of the page the observation is about. */
70
+ "part"
71
+ /** Which page, which revision of it, and which form was served. */
72
+ | "page"
73
+ /** What was observed about the part — when, how long, open or closed. */
74
+ | "observation"
75
+ /**
76
+ * The one visit the delivery belongs to.
77
+ *
78
+ * The narrowest scope anything here is correlated at, and the only one about
79
+ * a visit rather than about a page (0146).
80
+ */
81
+ | "page-view"
82
+ /** The delivery itself — when it was sent, and what it carried. */
83
+ | "delivery";
84
+ /**
85
+ * The closed set, for a surface grouping a notice by what its fields are about.
86
+ *
87
+ * **There is deliberately no member for the reader.** Every field of every
88
+ * batch is about one of these five things, which is rule 1 stated as a type
89
+ * rather than as a sentence: a field that needed a sixth member would be a
90
+ * field about a person, and adding one is a decision record and not a
91
+ * judgement call inside a pull request.
92
+ */
93
+ export declare const FIELD_SUBJECTS: readonly FieldSubject[];
94
+ /** One line per subject, addressed to the reader, for a surface grouping a notice. */
95
+ export declare const describeFieldSubject: (subject: FieldSubject) => string;
96
+ /** One field of a payload, and what it says. */
97
+ export type CollectedField = {
98
+ /** The field's name in the delivery, which is what a reader comparing this to a payload sees. */
99
+ readonly field: string;
100
+ /** What it is about. */
101
+ readonly subject: FieldSubject;
102
+ /** One sentence, addressed to the reader. */
103
+ readonly says: string;
104
+ };
105
+ /** A field as the tables below hold it, before its name is read off the key. */
106
+ type FieldNote = Omit<CollectedField, "field">;
107
+ /**
108
+ * Every field of one shape, keyed by the shape's own fields.
109
+ *
110
+ * `Required` is what makes an optional field — `within`, `view`, `audience`,
111
+ * `first` — as mandatory to describe as any other. A reader is owed a sentence
112
+ * about a field that is sometimes there.
113
+ */
114
+ type FieldsOf<Shape> = {
115
+ readonly [Field in keyof Required<Shape>]: FieldNote;
116
+ };
117
+ /**
118
+ * Every kind's fields.
119
+ *
120
+ * Spread from {@link ADDRESS_FIELDS} rather than written five times, with the
121
+ * per-kind annotation doing the checking: the three shared entries plus
122
+ * whatever that kind adds has to be exactly the fields the schema gives it.
123
+ */
124
+ export declare const SIGNAL_FIELDS: {
125
+ readonly [Kind in ReaderSignalKind]: FieldsOf<Extract<ReaderSignal, {
126
+ kind: Kind;
127
+ }>>;
128
+ };
129
+ /** What travels with a delivery, whatever observations are in it. */
130
+ export declare const DELIVERY_FIELDS: FieldsOf<ReaderSignalBatch>;
131
+ /** Something a reader signal never carries, whatever a deployment configures. */
132
+ export type Refusal =
133
+ /**
134
+ * No identifier for a person or a device, and nothing standing in for one.
135
+ *
136
+ * The first clause of rule 1. The second half of the sentence is the half
137
+ * that matters to somebody who has read a privacy policy before: an
138
+ * identifier nobody set is still an identifier.
139
+ */
140
+ "no-identifier"
141
+ /** No signature derived from a device, a browser or its settings. */
142
+ | "no-fingerprint"
143
+ /** Nothing the page said to you and nothing you said to it. */
144
+ | "no-content"
145
+ /** No cursor, no scroll trace, no recording. */
146
+ | "no-pointer-path"
147
+ /** Nothing that joins one visit to another. */
148
+ | "no-stitching"
149
+ /** Nothing derived from your address outlives the request it arrived on. */
150
+ | "no-address";
151
+ /** The closed set, for a surface listing what is refused. */
152
+ export declare const REFUSALS: readonly Refusal[];
153
+ /** One line per refusal, addressed to the reader. */
154
+ export declare const describeRefusal: (refusal: Refusal) => string;
155
+ /** Where a deployment counts its readers from, or that it does not. */
156
+ export type RegionNotice = {
157
+ /**
158
+ * The page views a country needs before it is published at all, or `null`
159
+ * where no country is read.
160
+ *
161
+ * `null` is *nothing about where you are is read*, which is a different
162
+ * sentence from *your country is counted and will not be published until
163
+ * enough others share it* — and the difference is the whole of what a floor
164
+ * is for. A country with a handful of views in it is a person (§7).
165
+ */
166
+ readonly floor: number | null;
167
+ };
168
+ /** One or two sentences about where readers are counted from, addressed to the reader. */
169
+ export declare const describeRegionNotice: (notice: RegionNotice) => string;
170
+ /**
171
+ * How often the deployment's own sweep runs, or that it has not said.
172
+ *
173
+ * The one thing a reader of {@link CollectionNotice.bufferMs} could not find
174
+ * out. `bufferMs` is the age at which a delivery becomes *ripe* — ready to be
175
+ * counted into the totals and deleted — and nothing in `src/signals/` deletes
176
+ * it: a host calls {@link collectReaderSignals} from a cron, a deploy hook or
177
+ * by hand (0146, 0158). So a deployment that never scheduled the sweep keeps
178
+ * every delivery for ever while its notice names an hour, and *a delivery is
179
+ * kept until it is 60 minutes old* was read by somebody with no way of hearing
180
+ * *…or indefinitely*.
181
+ *
182
+ * The deployment is the only party that knows how often it sweeps, so it states
183
+ * it — the shape `CollectionSchedule` already takes for the operator's half of
184
+ * the same fact
185
+ * ([0274](../../decisions/0274-a-page-view-row-says-when-the-fold-last-touched-it-and-a-stall-is-judged-against-a-schedule-the-deployment-hands-in.md)).
186
+ * A framework that guessed an interval would publish a ceiling nobody promised.
187
+ *
188
+ * **Two states rather than a nullable number**, because the ceiling has to be
189
+ * unreachable where no schedule was stated: a surface cannot print *gone within
190
+ * 70 minutes* on a deployment that promised nothing, which is the one way this
191
+ * field could make a notice overstate.
192
+ */
193
+ export type SweepNotice = {
194
+ readonly state: "stated";
195
+ /** The longest the deployment lets pass between sweeps, as it stated it. */
196
+ readonly everyMs: number;
197
+ /**
198
+ * The longest a delivery can live: the later of its two windows, plus one
199
+ * sweep interval.
200
+ *
201
+ * A sweep adds because a delivery does not go the instant it is eligible
202
+ * but at the next run, which is the arithmetic
203
+ * `CollectionSchedule.foldsWithinMs` spells out for the operator's half
204
+ * of this question (0274) — so **this is the number the retention check
205
+ * is given**, and a deployment states the interval once rather than
206
+ * keeping a reader's ceiling and an operator's threshold in step by hand.
207
+ *
208
+ * **The later of the two windows rather than their sum** (0351). A
209
+ * delivery is counted once it is `bufferMs` old and deleted once it is
210
+ * `keptMs` old, and both are measured from the same instant — the moment
211
+ * it arrived — so the second condition is met at the later of the two
212
+ * ages, not after one window has elapsed and then the other. Where the
213
+ * kept window is the shorter of the two, which is an odd but legal
214
+ * configuration, the delivery still has to be counted before it may go,
215
+ * and the maximum says exactly that.
216
+ */
217
+ readonly goneWithinMs: number;
218
+ }
219
+ /** Nothing was stated, so nothing here says when a ripe delivery actually goes. */
220
+ | {
221
+ readonly state: "unstated";
222
+ };
223
+ /** What a published page reports, and what it refuses to. */
224
+ export type CollectionNotice = {
225
+ /** The kinds this configuration broadcasts, in the vocabulary's order. */
226
+ readonly collects: readonly CollectedKind[];
227
+ /** What travels with every delivery. */
228
+ readonly delivery: readonly CollectedField[];
229
+ /** What is never collected, whatever else is configured. */
230
+ readonly refuses: readonly Refusal[];
231
+ /** Where readers are counted from, or that they are not. */
232
+ readonly region: RegionNotice;
233
+ /**
234
+ * How long a delivery waits before it is counted into the totals, in
235
+ * milliseconds.
236
+ *
237
+ * The deployment's own number (`collect.ts`). **It was the bound on the life
238
+ * of the page-view key and is not any more** (0351): a counted delivery used
239
+ * to be deleted in the same operation, and is now kept for
240
+ * {@link CollectionNotice.keptMs}. **The framework cannot promise the moment
241
+ * either sweep runs**, because a host schedules them: this is the age at
242
+ * which a delivery becomes ripe, not a guarantee about when the next run
243
+ * happens. What the deployment itself promises about that is
244
+ * {@link CollectionNotice.sweep}, and {@link describeBuffer} says all three
245
+ * together.
246
+ */
247
+ readonly bufferMs: number;
248
+ /**
249
+ * How long a delivery itself is kept, measured from when it arrived, in
250
+ * milliseconds.
251
+ *
252
+ * The honest bound on the life of the page-view key, and the number that
253
+ * makes this notice true since 5 November: individual deliveries are kept —
254
+ * thirty days by default — so that a deployment can look at them rather than
255
+ * only at counters (0349), and a notice that went on saying a delivery was
256
+ * deleted an hour after it arrived would be telling every reader of a privacy
257
+ * page something the deployment had stopped doing.
258
+ *
259
+ * Longer than {@link CollectionNotice.bufferMs} on any ordinary
260
+ * configuration, and the ceiling is taken over both rather than off this one,
261
+ * because a delivery is never deleted before it is counted whichever of the
262
+ * two windows is shorter (`expire.ts`).
263
+ */
264
+ readonly keptMs: number;
265
+ /**
266
+ * How often this deployment sweeps, where it has stated it.
267
+ *
268
+ * The half of retention that is not the framework's to promise, and the half
269
+ * a reader of the two windows alone would assume. {@link describeBuffer}
270
+ * takes them together for that reason: an age with no sweep beside it is a
271
+ * sentence that reads like a deletion and is not one.
272
+ *
273
+ * **One stated interval covers both sweeps**, because a deployment runs them
274
+ * from one place — counting and then expiring, in that order, in one cron
275
+ * route (0351). A deployment that ran them on two schedules would be stating
276
+ * the longer of the two here, which is what the ceiling needs.
277
+ */
278
+ readonly sweep: SweepNotice;
279
+ };
280
+ /** One kind of observation, with the fields it carries. */
281
+ export type CollectedKind = {
282
+ readonly kind: ReaderSignalKind;
283
+ /** What the page observed, addressed to the reader. */
284
+ readonly observes: string;
285
+ /** Every field that kind carries, including the ones it sometimes omits. */
286
+ readonly carries: readonly CollectedField[];
287
+ };
288
+ /**
289
+ * Every part of how long a delivery lives: the age it is counted at, the age it
290
+ * is deleted at, and how often the deployment's sweep runs.
291
+ *
292
+ * A `Pick` of the notice rather than three arguments, so that the sentence
293
+ * cannot be built from some of them. The ripeness age alone reads as a deletion
294
+ * and is not one — and since 5 November it is not even the deletion's age
295
+ * (0351).
296
+ */
297
+ export type DeliveryRetention = Pick<CollectionNotice, "bufferMs" | "keptMs" | "sweep">;
298
+ /**
299
+ * How long a delivery lives, addressed to the reader.
300
+ *
301
+ * It takes the retention whole, because the two ages are the halves the
302
+ * framework knows and the sweep is the half it cannot promise, and a notice
303
+ * that published an age without the sweep said *a delivery is kept until it is
304
+ * 60 minutes old* to a reader who had no way of hearing *…or for ever, if
305
+ * nobody runs the sweep*. Where a schedule was stated the sentence ends on a
306
+ * ceiling a reader can hold the deployment to; where none was, it says that in
307
+ * as many words rather than leaving the ages to be read as a promise.
308
+ *
309
+ * **Two ages since 5 November, and saying one of them would be the lie** (0349,
310
+ * 0351). A delivery is counted at the first age and deleted at the second, and
311
+ * the sentence is explicit about what the gap is for: so that the deployment
312
+ * can look at the deliveries behind its totals. A reader told only *counted
313
+ * into totals* would reasonably assume the delivery was gone.
314
+ */
315
+ export declare const describeBuffer: (retention: DeliveryRetention) => string;
316
+ /** The configuration a notice is of. */
317
+ export type NoticeRequest = {
318
+ /**
319
+ * The options the page is broadcast with — the same object, so that a notice
320
+ * and the page it is about cannot disagree about which kinds are reported.
321
+ *
322
+ * Only `kinds` is read. `types` and `within` narrow collection below what the
323
+ * notice says, which is the ceiling rule above.
324
+ */
325
+ readonly page?: Pick<ReaderSignalOptions, "kinds">;
326
+ /**
327
+ * The window the deployment collects on, from its own `CollectionRequest`
328
+ * (`collect.ts`). The default when absent.
329
+ *
330
+ * Reported as given rather than clamped: `collect.ts` is what refuses a
331
+ * window below its minimum, and a notice that silently reported a different
332
+ * number from the one a deployment configured would be a second rule about
333
+ * one setting.
334
+ */
335
+ readonly windowMs?: number;
336
+ /**
337
+ * The region counting this deployment's intake does, where it does any.
338
+ *
339
+ * Absent is *no country is read*, which is the default: reading one is
340
+ * something an intake is configured to do (§7). A floor below the published
341
+ * minimum is raised to it, by the same helper the region map itself uses.
342
+ */
343
+ readonly region?: {
344
+ readonly floor?: number | undefined;
345
+ };
346
+ /**
347
+ * How often this deployment's sweep runs, where it has stated it.
348
+ *
349
+ * Absent is *nothing is stated*, which is the honest default: nothing in this
350
+ * subsystem schedules a sweep, so a notice that assumed one would publish a
351
+ * ceiling no deployment promised. A value that is not a positive, finite
352
+ * number of milliseconds is read the same way — the notice may always
353
+ * promise a reader less than the deployment knows and may never promise more,
354
+ * and the operator-facing half, where a value that could not be read is said
355
+ * out loud, is a deployment's own settings (0317).
356
+ */
357
+ readonly sweep?: {
358
+ readonly everyMs: number;
359
+ };
360
+ /**
361
+ * The window this deployment keeps individual deliveries for, from its own
362
+ * `ExpiryRequest` (`expire.ts`). The default when absent.
363
+ *
364
+ * Reported as given rather than clamped, as the collection window is and for
365
+ * the same reason: `expire.ts` is what refuses a window below its minimum.
366
+ *
367
+ * **Absent is the default rather than *nothing is kept*,** which is the one
368
+ * place this field differs in spirit from the sweep beside it. A deployment
369
+ * that calls the expiry sweep with no window gets thirty days (0349), so a
370
+ * notice that read an absent setting as *deleted the moment it is counted*
371
+ * would understate what is kept — and this module's standing rule is that it
372
+ * may overstate what is collected and may never overstate what is deleted.
373
+ */
374
+ readonly keptMs?: number;
375
+ };
376
+ /**
377
+ * What a page broadcast with these options reports, as a deployment may publish
378
+ * it.
379
+ *
380
+ * Pure, and allocation-per-call: no store, no clock, no DOM.
381
+ *
382
+ * The kinds come out in the vocabulary's order and each appears once, whatever
383
+ * order a configuration names them in and however often — a notice is read by
384
+ * somebody who did not write the configuration, and *dwelled, dwelled, viewed*
385
+ * is a leak of how the options were typed rather than a fact about the page.
386
+ */
387
+ export declare const collectionNoticeOf: (request?: NoticeRequest) => CollectionNotice;
388
+ export {};
389
+ //# sourceMappingURL=notice.d.ts.map
@@ -0,0 +1,250 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ import { DEFAULT_READER_SIGNAL_WINDOW_MS } from "./collect.js";
3
+ import { DEFAULT_READER_EVENT_RETENTION_MS } from "./expire.js";
4
+ import { regionFloorOf } from "./region.js";
5
+ import { READER_SIGNAL_KINDS, } from "./signal.js";
6
+ /**
7
+ * The closed set, for a surface grouping a notice by what its fields are about.
8
+ *
9
+ * **There is deliberately no member for the reader.** Every field of every
10
+ * batch is about one of these five things, which is rule 1 stated as a type
11
+ * rather than as a sentence: a field that needed a sixth member would be a
12
+ * field about a person, and adding one is a decision record and not a
13
+ * judgement call inside a pull request.
14
+ */
15
+ export const FIELD_SUBJECTS = everyMemberOf()([
16
+ "part",
17
+ "page",
18
+ "observation",
19
+ "page-view",
20
+ "delivery",
21
+ ]);
22
+ /** One line per subject, addressed to the reader, for a surface grouping a notice. */
23
+ export const describeFieldSubject = (subject) => {
24
+ switch (subject) {
25
+ case "part":
26
+ return "which part of the page it is about";
27
+ case "page":
28
+ return "which page you were reading, and which version of it";
29
+ case "observation":
30
+ return "what was observed about that part";
31
+ case "page-view":
32
+ return "this one visit to this one page, and nothing outside it";
33
+ case "delivery":
34
+ return "the delivery itself";
35
+ }
36
+ };
37
+ const fieldsOf = (table) => Object.entries(table).map(([field, note]) => ({ field, ...note }));
38
+ /** The three fields every kind carries: which kind it is, and which part it is about. */
39
+ const ADDRESS_FIELDS = {
40
+ kind: {
41
+ subject: "observation",
42
+ says: "which of the five kinds of observation this is, and nothing beyond the five",
43
+ },
44
+ nodeId: {
45
+ subject: "part",
46
+ says: "which part of the page this is about, as the page's own name for that part",
47
+ },
48
+ type: {
49
+ subject: "part",
50
+ says: "what kind of part it is — a section, a card, a link — and never what it says",
51
+ },
52
+ };
53
+ const AT = {
54
+ subject: "observation",
55
+ says: "when it happened, to the millisecond, by your browser's clock",
56
+ };
57
+ const WITHIN = {
58
+ subject: "part",
59
+ says: "the parts of the page it happened inside, named the same way — so that a press can be counted" +
60
+ " against the section it was in and not only against the button",
61
+ };
62
+ /**
63
+ * Every kind's fields.
64
+ *
65
+ * Spread from {@link ADDRESS_FIELDS} rather than written five times, with the
66
+ * per-kind annotation doing the checking: the three shared entries plus
67
+ * whatever that kind adds has to be exactly the fields the schema gives it.
68
+ */
69
+ export const SIGNAL_FIELDS = {
70
+ viewed: { ...ADDRESS_FIELDS, at: AT },
71
+ dwelled: {
72
+ ...ADDRESS_FIELDS,
73
+ ms: {
74
+ subject: "observation",
75
+ says: "how long it was on your screen since the last delivery, in milliseconds",
76
+ },
77
+ },
78
+ activated: { ...ADDRESS_FIELDS, at: AT, within: WITHIN },
79
+ disclosed: {
80
+ ...ADDRESS_FIELDS,
81
+ open: { subject: "observation", says: "whether it was opened or closed" },
82
+ at: AT,
83
+ within: WITHIN,
84
+ },
85
+ completed: { ...ADDRESS_FIELDS, at: AT, within: WITHIN },
86
+ };
87
+ /** What travels with a delivery, whatever observations are in it. */
88
+ export const DELIVERY_FIELDS = {
89
+ treeId: { subject: "page", says: "which page it was" },
90
+ revision: {
91
+ subject: "page",
92
+ says: "which revision of that page you were served, so that an observation keeps its meaning after the page changes",
93
+ },
94
+ sentAt: { subject: "delivery", says: "when the delivery left your browser" },
95
+ audience: {
96
+ subject: "page",
97
+ says: "which form of the page you were served, by the name the deployment gave that form — a name for a group," +
98
+ " never a name for you, and nothing about why you matched it",
99
+ },
100
+ view: {
101
+ subject: "page-view",
102
+ says: "a random key that ties this delivery to the others from the same visit to this page, so that steps can be" +
103
+ " counted in order; it is tied to nothing else, it is never stored beside the counters, and it is gone when" +
104
+ " the delivery is",
105
+ },
106
+ first: {
107
+ subject: "page-view",
108
+ says: "whether this was the opening delivery of the visit, which is how arrivals are counted once rather than once per delivery",
109
+ },
110
+ signals: { subject: "delivery", says: "the observations themselves" },
111
+ };
112
+ /** The closed set, for a surface listing what is refused. */
113
+ export const REFUSALS = everyMemberOf()([
114
+ "no-identifier",
115
+ "no-fingerprint",
116
+ "no-content",
117
+ "no-pointer-path",
118
+ "no-stitching",
119
+ "no-address",
120
+ ]);
121
+ /** One line per refusal, addressed to the reader. */
122
+ export const describeRefusal = (refusal) => {
123
+ switch (refusal) {
124
+ case "no-identifier":
125
+ return "nothing that identifies you: no account, no visitor id, no device id, and nothing derived from your browser to stand in for one";
126
+ case "no-fingerprint":
127
+ return "nothing about your device, your browser or your settings, and so nothing that could be combined into a signature for you";
128
+ case "no-content":
129
+ return "nothing the page showed you and nothing you typed into it: no text, no link target, no form value";
130
+ case "no-pointer-path":
131
+ return "no cursor positions, no scroll trace, and no recording of your session";
132
+ case "no-stitching":
133
+ return "nothing that joins this visit to another one, here or on any other page, so there is no history of you to hold";
134
+ case "no-address":
135
+ return "nothing derived from the address your request arrived from outlives the request, and the address itself is never stored";
136
+ }
137
+ };
138
+ /** One or two sentences about where readers are counted from, addressed to the reader. */
139
+ export const describeRegionNotice = (notice) => notice.floor === null
140
+ ? "nothing about where you are is read, not even your country"
141
+ : `the country your request arrives from is counted, and nothing finer than the country; a country is published only once at least ${notice.floor} visits are counted in it, and the address it was read from is never stored`;
142
+ /** What each kind observes, in the reader's own terms rather than the browser's. */
143
+ const OBSERVES = {
144
+ viewed: "that a part of the page came onto your screen",
145
+ dwelled: "how long a part of the page stayed on your screen",
146
+ activated: "that you used a link, a button or a field, and which part of the page it was in",
147
+ disclosed: "that you opened or closed a part of the page",
148
+ completed: "that a form you filled in was submitted — that it left your browser, and never what was in it",
149
+ };
150
+ /**
151
+ * A length of time as a notice says it.
152
+ *
153
+ * Minutes above a minute and seconds below it, because the one number here a
154
+ * deployment could set low is the buffer and `collect.ts` floors it at a minute
155
+ * — so a notice reading *0 minutes* would be reporting a window the collector
156
+ * would refuse to run on.
157
+ *
158
+ * **Days above a day**, which the kept window asked for (0351): thirty days is
159
+ * the default a deployment keeps individual deliveries for, and *43200 minutes*
160
+ * is a number no reader of a privacy page can hold. The break is at a day
161
+ * rather than at an hour so that every figure a notice published before the
162
+ * kept window existed still reads exactly as it did — an hour is *60 minutes*
163
+ * here, as it has been, and the one new figure is the one that needed a bigger
164
+ * unit.
165
+ */
166
+ const inWords = (ms) => {
167
+ if (ms < 60_000) {
168
+ const seconds = Math.round(ms / 1000);
169
+ return seconds === 1 ? "a second" : `${seconds} seconds`;
170
+ }
171
+ if (ms < 24 * 60 * 60_000) {
172
+ const minutes = Math.round(ms / 60_000);
173
+ return minutes === 1 ? "a minute" : `${minutes} minutes`;
174
+ }
175
+ const days = Math.round(ms / (24 * 60 * 60_000));
176
+ return days === 1 ? "a day" : `${days} days`;
177
+ };
178
+ /**
179
+ * How long a delivery lives, addressed to the reader.
180
+ *
181
+ * It takes the retention whole, because the two ages are the halves the
182
+ * framework knows and the sweep is the half it cannot promise, and a notice
183
+ * that published an age without the sweep said *a delivery is kept until it is
184
+ * 60 minutes old* to a reader who had no way of hearing *…or for ever, if
185
+ * nobody runs the sweep*. Where a schedule was stated the sentence ends on a
186
+ * ceiling a reader can hold the deployment to; where none was, it says that in
187
+ * as many words rather than leaving the ages to be read as a promise.
188
+ *
189
+ * **Two ages since 5 November, and saying one of them would be the lie** (0349,
190
+ * 0351). A delivery is counted at the first age and deleted at the second, and
191
+ * the sentence is explicit about what the gap is for: so that the deployment
192
+ * can look at the deliveries behind its totals. A reader told only *counted
193
+ * into totals* would reasonably assume the delivery was gone.
194
+ */
195
+ export const describeBuffer = (retention) => {
196
+ const counts = `a delivery is counted into this deployment's totals once it is ${inWords(retention.bufferMs)} old`;
197
+ const kept = `it is then kept for ${inWords(retention.keptMs)} from when it arrived, so that this deployment can look at the deliveries its totals were made from, and its own sweep is what deletes it`;
198
+ const totals = "the totals it leaves behind have nobody in them, and they are kept";
199
+ return retention.sweep.state === "stated"
200
+ ? `${counts}; ${kept}; that sweep runs at least every ${inWords(retention.sweep.everyMs)}, so a delivery is gone within ${inWords(retention.sweep.goneWithinMs)} of arriving — the key tying one visit together exists until then and nowhere else; ${totals}`
201
+ : `${counts}; ${kept}; this deployment has not said how often that sweep runs, so nothing here promises when a kept delivery actually goes — the key tying one visit together exists until the sweep takes it and nowhere else; ${totals}`;
202
+ };
203
+ /**
204
+ * What a stated interval becomes on a notice.
205
+ *
206
+ * The ceiling is derived here and nowhere else, so that a surface cannot print
207
+ * a number that disagrees with the age beside it: it is the ripeness window
208
+ * plus one sweep, which is the same addition the stall check asks a deployment
209
+ * for in one number (0274).
210
+ *
211
+ * **Anything that is not a positive, finite interval is `unstated`** rather
212
+ * than an error or a nought. A nought would publish *gone within 60 minutes* on
213
+ * a deployment that sweeps when somebody remembers to, and this module's one
214
+ * standing rule is that it may overstate what is collected and may never
215
+ * overstate what is deleted.
216
+ */
217
+ const sweepNoticeOf = (everyMs, bufferMs, keptMs) => everyMs === undefined || !Number.isFinite(everyMs) || everyMs <= 0
218
+ ? { state: "unstated" }
219
+ : { state: "stated", everyMs, goneWithinMs: Math.max(bufferMs, keptMs) + everyMs };
220
+ /**
221
+ * What a page broadcast with these options reports, as a deployment may publish
222
+ * it.
223
+ *
224
+ * Pure, and allocation-per-call: no store, no clock, no DOM.
225
+ *
226
+ * The kinds come out in the vocabulary's order and each appears once, whatever
227
+ * order a configuration names them in and however often — a notice is read by
228
+ * somebody who did not write the configuration, and *dwelled, dwelled, viewed*
229
+ * is a leak of how the options were typed rather than a fact about the page.
230
+ */
231
+ export const collectionNoticeOf = (request = {}) => {
232
+ const asked = request.page?.kinds;
233
+ const bufferMs = request.windowMs ?? DEFAULT_READER_SIGNAL_WINDOW_MS;
234
+ const keptMs = request.keptMs ?? DEFAULT_READER_EVENT_RETENTION_MS;
235
+ const collects = READER_SIGNAL_KINDS.filter((kind) => asked === undefined || asked.includes(kind)).map((kind) => ({
236
+ kind,
237
+ observes: OBSERVES[kind],
238
+ carries: fieldsOf(SIGNAL_FIELDS[kind]),
239
+ }));
240
+ return {
241
+ collects,
242
+ delivery: fieldsOf(DELIVERY_FIELDS),
243
+ refuses: REFUSALS,
244
+ region: { floor: request.region === undefined ? null : regionFloorOf(request.region.floor) },
245
+ bufferMs,
246
+ keptMs,
247
+ sweep: sweepNoticeOf(request.sweep?.everyMs, bufferMs, keptMs),
248
+ };
249
+ };
250
+ //# sourceMappingURL=notice.js.map