@jam-overture/loom 0.1.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 (401) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +743 -0
  3. package/dist/catalogue.d.ts +70 -0
  4. package/dist/catalogue.js +88 -0
  5. package/dist/cli/args.d.ts +17 -0
  6. package/dist/cli/args.js +83 -0
  7. package/dist/cli/filesystem.d.ts +15 -0
  8. package/dist/cli/filesystem.js +31 -0
  9. package/dist/cli/index.d.ts +12 -0
  10. package/dist/cli/index.js +12 -0
  11. package/dist/cli/main.d.ts +3 -0
  12. package/dist/cli/main.js +30 -0
  13. package/dist/cli/namespace.d.ts +40 -0
  14. package/dist/cli/namespace.js +40 -0
  15. package/dist/cli/plan.d.ts +84 -0
  16. package/dist/cli/plan.js +113 -0
  17. package/dist/cli/run.d.ts +17 -0
  18. package/dist/cli/run.js +75 -0
  19. package/dist/cli/templates.d.ts +43 -0
  20. package/dist/cli/templates.js +134 -0
  21. package/dist/closed-set.d.ts +34 -0
  22. package/dist/closed-set.js +34 -0
  23. package/dist/data/adapter.d.ts +123 -0
  24. package/dist/data/adapter.js +91 -0
  25. package/dist/data/binding.d.ts +48 -0
  26. package/dist/data/binding.js +39 -0
  27. package/dist/data/catalogue.d.ts +26 -0
  28. package/dist/data/catalogue.js +6 -0
  29. package/dist/data/index.d.ts +14 -0
  30. package/dist/data/index.js +14 -0
  31. package/dist/data/plan.d.ts +58 -0
  32. package/dist/data/plan.js +0 -0
  33. package/dist/data/resolution.d.ts +91 -0
  34. package/dist/data/resolution.js +96 -0
  35. package/dist/data/resolve.d.ts +46 -0
  36. package/dist/data/resolve.js +37 -0
  37. package/dist/data/source.d.ts +40 -0
  38. package/dist/data/source.js +45 -0
  39. package/dist/deadline.d.ts +57 -0
  40. package/dist/deadline.js +78 -0
  41. package/dist/frame/catalogue.d.ts +24 -0
  42. package/dist/frame/catalogue.js +5 -0
  43. package/dist/frame/index.d.ts +12 -0
  44. package/dist/frame/index.js +12 -0
  45. package/dist/frame/origin.d.ts +87 -0
  46. package/dist/frame/origin.js +114 -0
  47. package/dist/frame/resolution.d.ts +85 -0
  48. package/dist/frame/resolution.js +79 -0
  49. package/dist/grammar.d.ts +26 -0
  50. package/dist/grammar.js +28 -0
  51. package/dist/ids.d.ts +57 -0
  52. package/dist/ids.js +104 -0
  53. package/dist/index.d.ts +26 -0
  54. package/dist/index.js +26 -0
  55. package/dist/interactivity.d.ts +50 -0
  56. package/dist/interactivity.js +22 -0
  57. package/dist/interpretation/anthropic.d.ts +22 -0
  58. package/dist/interpretation/anthropic.js +76 -0
  59. package/dist/interpretation/client.d.ts +83 -0
  60. package/dist/interpretation/client.js +2 -0
  61. package/dist/interpretation/draft.d.ts +234 -0
  62. package/dist/interpretation/draft.js +84 -0
  63. package/dist/interpretation/index.d.ts +15 -0
  64. package/dist/interpretation/index.js +15 -0
  65. package/dist/interpretation/interpreter.d.ts +62 -0
  66. package/dist/interpretation/interpreter.js +151 -0
  67. package/dist/interpretation/materialize.d.ts +42 -0
  68. package/dist/interpretation/materialize.js +107 -0
  69. package/dist/interpretation/prompt.d.ts +229 -0
  70. package/dist/interpretation/prompt.js +285 -0
  71. package/dist/interpretation/render.d.ts +76 -0
  72. package/dist/interpretation/render.js +272 -0
  73. package/dist/interpretation/schema.d.ts +49 -0
  74. package/dist/interpretation/schema.js +131 -0
  75. package/dist/json.d.ts +35 -0
  76. package/dist/json.js +11 -0
  77. package/dist/paging.d.ts +60 -0
  78. package/dist/paging.js +49 -0
  79. package/dist/primitive-type.d.ts +32 -0
  80. package/dist/primitive-type.js +39 -0
  81. package/dist/render/addressing.d.ts +59 -0
  82. package/dist/render/addressing.js +60 -0
  83. package/dist/render/anchor.d.ts +105 -0
  84. package/dist/render/anchor.js +84 -0
  85. package/dist/render/behaviour-adjust.d.ts +62 -0
  86. package/dist/render/behaviour-adjust.js +78 -0
  87. package/dist/render/behaviour-copy.d.ts +53 -0
  88. package/dist/render/behaviour-copy.js +75 -0
  89. package/dist/render/behaviour-disclose.d.ts +74 -0
  90. package/dist/render/behaviour-disclose.js +77 -0
  91. package/dist/render/behaviour-present.d.ts +123 -0
  92. package/dist/render/behaviour-present.js +173 -0
  93. package/dist/render/behaviour.d.ts +243 -0
  94. package/dist/render/behaviour.js +284 -0
  95. package/dist/render/control.d.ts +81 -0
  96. package/dist/render/control.js +80 -0
  97. package/dist/render/decorative.d.ts +62 -0
  98. package/dist/render/decorative.js +2 -0
  99. package/dist/render/diagnostics.d.ts +260 -0
  100. package/dist/render/diagnostics.js +61 -0
  101. package/dist/render/disclosed.d.ts +37 -0
  102. package/dist/render/disclosed.js +37 -0
  103. package/dist/render/editable.d.ts +34 -0
  104. package/dist/render/editable.js +35 -0
  105. package/dist/render/frame.d.ts +42 -0
  106. package/dist/render/frame.js +31 -0
  107. package/dist/render/index.d.ts +35 -0
  108. package/dist/render/index.js +35 -0
  109. package/dist/render/inline-variables.d.ts +77 -0
  110. package/dist/render/inline-variables.js +220 -0
  111. package/dist/render/presented.d.ts +82 -0
  112. package/dist/render/presented.js +82 -0
  113. package/dist/render/primitive.d.ts +228 -0
  114. package/dist/render/primitive.js +36 -0
  115. package/dist/render/props.d.ts +48 -0
  116. package/dist/render/props.js +2 -0
  117. package/dist/render/reads.d.ts +73 -0
  118. package/dist/render/reads.js +45 -0
  119. package/dist/render/render.d.ts +164 -0
  120. package/dist/render/render.js +571 -0
  121. package/dist/render/request.d.ts +111 -0
  122. package/dist/render/request.js +60 -0
  123. package/dist/render/text.d.ts +91 -0
  124. package/dist/render/text.js +44 -0
  125. package/dist/render/theme.d.ts +61 -0
  126. package/dist/render/theme.js +52 -0
  127. package/dist/reserved-props.d.ts +35 -0
  128. package/dist/reserved-props.js +45 -0
  129. package/dist/result.d.ts +27 -0
  130. package/dist/result.js +30 -0
  131. package/dist/role.d.ts +71 -0
  132. package/dist/role.js +22 -0
  133. package/dist/runtime/analysis.d.ts +149 -0
  134. package/dist/runtime/analysis.js +187 -0
  135. package/dist/runtime/assessment.d.ts +35 -0
  136. package/dist/runtime/assessment.js +13 -0
  137. package/dist/runtime/disposition.d.ts +102 -0
  138. package/dist/runtime/disposition.js +59 -0
  139. package/dist/runtime/events.d.ts +187 -0
  140. package/dist/runtime/events.js +7 -0
  141. package/dist/runtime/gate.d.ts +43 -0
  142. package/dist/runtime/gate.js +169 -0
  143. package/dist/runtime/index.d.ts +27 -0
  144. package/dist/runtime/index.js +27 -0
  145. package/dist/runtime/intent.d.ts +60 -0
  146. package/dist/runtime/intent.js +36 -0
  147. package/dist/runtime/interpreter.d.ts +117 -0
  148. package/dist/runtime/interpreter.js +46 -0
  149. package/dist/runtime/inverse-interpreter.d.ts +90 -0
  150. package/dist/runtime/inverse-interpreter.js +56 -0
  151. package/dist/runtime/inverse.d.ts +87 -0
  152. package/dist/runtime/inverse.js +48 -0
  153. package/dist/runtime/narration.d.ts +24 -0
  154. package/dist/runtime/narration.js +36 -0
  155. package/dist/runtime/nesting.d.ts +31 -0
  156. package/dist/runtime/nesting.js +46 -0
  157. package/dist/runtime/pipeline.d.ts +124 -0
  158. package/dist/runtime/pipeline.js +178 -0
  159. package/dist/runtime/policy-fingerprint.d.ts +29 -0
  160. package/dist/runtime/policy-fingerprint.js +119 -0
  161. package/dist/runtime/policy-source.d.ts +42 -0
  162. package/dist/runtime/policy-source.js +8 -0
  163. package/dist/runtime/policy.d.ts +156 -0
  164. package/dist/runtime/policy.js +107 -0
  165. package/dist/runtime/proposal.d.ts +423 -0
  166. package/dist/runtime/proposal.js +109 -0
  167. package/dist/runtime/redirection.d.ts +53 -0
  168. package/dist/runtime/redirection.js +38 -0
  169. package/dist/runtime/repointing.d.ts +71 -0
  170. package/dist/runtime/repointing.js +0 -0
  171. package/dist/runtime/reversibility.d.ts +36 -0
  172. package/dist/runtime/reversibility.js +39 -0
  173. package/dist/runtime/stake-level.d.ts +33 -0
  174. package/dist/runtime/stake-level.js +58 -0
  175. package/dist/runtime/stakes.d.ts +47 -0
  176. package/dist/runtime/stakes.js +305 -0
  177. package/dist/runtime/vocabulary.d.ts +122 -0
  178. package/dist/runtime/vocabulary.js +87 -0
  179. package/dist/sdk/audit.d.ts +195 -0
  180. package/dist/sdk/audit.js +128 -0
  181. package/dist/sdk/catalogue.d.ts +37 -0
  182. package/dist/sdk/catalogue.js +16 -0
  183. package/dist/sdk/conformance.d.ts +342 -0
  184. package/dist/sdk/conformance.js +494 -0
  185. package/dist/sdk/copy.d.ts +105 -0
  186. package/dist/sdk/copy.js +90 -0
  187. package/dist/sdk/definition.d.ts +242 -0
  188. package/dist/sdk/definition.js +64 -0
  189. package/dist/sdk/index.d.ts +19 -0
  190. package/dist/sdk/index.js +19 -0
  191. package/dist/sdk/interactivity.d.ts +29 -0
  192. package/dist/sdk/interactivity.js +34 -0
  193. package/dist/sdk/pairings.d.ts +124 -0
  194. package/dist/sdk/pairings.js +81 -0
  195. package/dist/sdk/registry.d.ts +162 -0
  196. package/dist/sdk/registry.js +329 -0
  197. package/dist/sdk/selection.d.ts +46 -0
  198. package/dist/sdk/selection.js +24 -0
  199. package/dist/sdk/text.d.ts +100 -0
  200. package/dist/sdk/text.js +105 -0
  201. package/dist/sdk/vocabulary.d.ts +39 -0
  202. package/dist/sdk/vocabulary.js +36 -0
  203. package/dist/signals/broadcast.d.ts +134 -0
  204. package/dist/signals/broadcast.js +451 -0
  205. package/dist/signals/collect.d.ts +184 -0
  206. package/dist/signals/collect.js +196 -0
  207. package/dist/signals/deliver.d.ts +64 -0
  208. package/dist/signals/deliver.js +85 -0
  209. package/dist/signals/fold.d.ts +112 -0
  210. package/dist/signals/fold.js +76 -0
  211. package/dist/signals/index.d.ts +31 -0
  212. package/dist/signals/index.js +31 -0
  213. package/dist/signals/ingest.d.ts +51 -0
  214. package/dist/signals/ingest.js +70 -0
  215. package/dist/signals/intake.d.ts +149 -0
  216. package/dist/signals/intake.js +154 -0
  217. package/dist/signals/journal.d.ts +94 -0
  218. package/dist/signals/journal.js +11 -0
  219. package/dist/signals/kinds.d.ts +22 -0
  220. package/dist/signals/kinds.js +22 -0
  221. package/dist/signals/ledger.d.ts +46 -0
  222. package/dist/signals/ledger.js +81 -0
  223. package/dist/signals/memory.d.ts +17 -0
  224. package/dist/signals/memory.js +99 -0
  225. package/dist/signals/migrate.d.ts +27 -0
  226. package/dist/signals/migrate.js +78 -0
  227. package/dist/signals/postgres.d.ts +7 -0
  228. package/dist/signals/postgres.js +295 -0
  229. package/dist/signals/rollup.d.ts +142 -0
  230. package/dist/signals/rollup.js +0 -0
  231. package/dist/signals/schema.d.ts +534 -0
  232. package/dist/signals/schema.js +92 -0
  233. package/dist/signals/signal.d.ts +381 -0
  234. package/dist/signals/signal.js +150 -0
  235. package/dist/signals/tally.d.ts +70 -0
  236. package/dist/signals/tally.js +2 -0
  237. package/dist/signals/view.d.ts +51 -0
  238. package/dist/signals/view.js +54 -0
  239. package/dist/store/attribution.d.ts +125 -0
  240. package/dist/store/attribution.js +116 -0
  241. package/dist/store/database.d.ts +14 -0
  242. package/dist/store/database.js +2 -0
  243. package/dist/store/driver.d.ts +29 -0
  244. package/dist/store/driver.js +39 -0
  245. package/dist/store/errors.d.ts +56 -0
  246. package/dist/store/errors.js +37 -0
  247. package/dist/store/index.d.ts +16 -0
  248. package/dist/store/index.js +16 -0
  249. package/dist/store/memory.d.ts +3 -0
  250. package/dist/store/memory.js +115 -0
  251. package/dist/store/migrate.d.ts +54 -0
  252. package/dist/store/migrate.js +122 -0
  253. package/dist/store/postgres-holds.d.ts +4 -0
  254. package/dist/store/postgres-holds.js +192 -0
  255. package/dist/store/postgres.d.ts +8 -0
  256. package/dist/store/postgres.js +262 -0
  257. package/dist/store/replay.d.ts +94 -0
  258. package/dist/store/replay.js +82 -0
  259. package/dist/store/revert.d.ts +116 -0
  260. package/dist/store/revert.js +243 -0
  261. package/dist/store/schema.d.ts +371 -0
  262. package/dist/store/schema.js +78 -0
  263. package/dist/store/source.d.ts +23 -0
  264. package/dist/store/source.js +37 -0
  265. package/dist/store/store.d.ts +231 -0
  266. package/dist/store/store.js +52 -0
  267. package/dist/store/undone.d.ts +18 -0
  268. package/dist/store/undone.js +89 -0
  269. package/dist/submit/catalogue.d.ts +20 -0
  270. package/dist/submit/catalogue.js +5 -0
  271. package/dist/submit/declaration.d.ts +39 -0
  272. package/dist/submit/declaration.js +30 -0
  273. package/dist/submit/endpoint.d.ts +131 -0
  274. package/dist/submit/endpoint.js +160 -0
  275. package/dist/submit/index.d.ts +13 -0
  276. package/dist/submit/index.js +13 -0
  277. package/dist/submit/plan.d.ts +49 -0
  278. package/dist/submit/plan.js +47 -0
  279. package/dist/submit/resolution.d.ts +61 -0
  280. package/dist/submit/resolution.js +64 -0
  281. package/dist/submit/resolve.d.ts +45 -0
  282. package/dist/submit/resolve.js +36 -0
  283. package/dist/telemetry/calibration.d.ts +132 -0
  284. package/dist/telemetry/calibration.js +151 -0
  285. package/dist/telemetry/episode.d.ts +140 -0
  286. package/dist/telemetry/episode.js +272 -0
  287. package/dist/telemetry/event.d.ts +2310 -0
  288. package/dist/telemetry/event.js +405 -0
  289. package/dist/telemetry/index.d.ts +15 -0
  290. package/dist/telemetry/index.js +15 -0
  291. package/dist/telemetry/journal.d.ts +116 -0
  292. package/dist/telemetry/journal.js +11 -0
  293. package/dist/telemetry/memory.d.ts +24 -0
  294. package/dist/telemetry/memory.js +75 -0
  295. package/dist/telemetry/migrate.d.ts +26 -0
  296. package/dist/telemetry/migrate.js +40 -0
  297. package/dist/telemetry/postgres.d.ts +6 -0
  298. package/dist/telemetry/postgres.js +139 -0
  299. package/dist/telemetry/retention.d.ts +131 -0
  300. package/dist/telemetry/retention.js +217 -0
  301. package/dist/telemetry/schema.d.ts +113 -0
  302. package/dist/telemetry/schema.js +33 -0
  303. package/dist/telemetry/sink.d.ts +42 -0
  304. package/dist/telemetry/sink.js +61 -0
  305. package/dist/testing/contracts.d.ts +34 -0
  306. package/dist/testing/contracts.js +34 -0
  307. package/dist/testing/definitions.d.ts +15 -0
  308. package/dist/testing/definitions.js +48 -0
  309. package/dist/testing/doubles.d.ts +94 -0
  310. package/dist/testing/doubles.js +141 -0
  311. package/dist/testing/episode-harness.d.ts +49 -0
  312. package/dist/testing/episode-harness.js +65 -0
  313. package/dist/testing/filesystem.d.ts +17 -0
  314. package/dist/testing/filesystem.js +17 -0
  315. package/dist/testing/fixtures.d.ts +57 -0
  316. package/dist/testing/fixtures.js +84 -0
  317. package/dist/testing/hold-contract.d.ts +19 -0
  318. package/dist/testing/hold-contract.js +374 -0
  319. package/dist/testing/index.d.ts +41 -0
  320. package/dist/testing/index.js +41 -0
  321. package/dist/testing/journal-contract.d.ts +17 -0
  322. package/dist/testing/journal-contract.js +353 -0
  323. package/dist/testing/model-replies.d.ts +34 -0
  324. package/dist/testing/model-replies.js +101 -0
  325. package/dist/testing/primitives.d.ts +7 -0
  326. package/dist/testing/primitives.js +29 -0
  327. package/dist/testing/reader-signal-contract.d.ts +38 -0
  328. package/dist/testing/reader-signal-contract.js +318 -0
  329. package/dist/testing/row-security.d.ts +17 -0
  330. package/dist/testing/row-security.js +21 -0
  331. package/dist/testing/store-contract.d.ts +25 -0
  332. package/dist/testing/store-contract.js +500 -0
  333. package/dist/theme/apply.d.ts +17 -0
  334. package/dist/theme/apply.js +60 -0
  335. package/dist/theme/contrast.d.ts +197 -0
  336. package/dist/theme/contrast.js +259 -0
  337. package/dist/theme/derive.d.ts +77 -0
  338. package/dist/theme/derive.js +167 -0
  339. package/dist/theme/faces.d.ts +73 -0
  340. package/dist/theme/faces.js +119 -0
  341. package/dist/theme/font-packs.d.ts +25 -0
  342. package/dist/theme/font-packs.js +257 -0
  343. package/dist/theme/index.d.ts +20 -0
  344. package/dist/theme/index.js +20 -0
  345. package/dist/theme/lab.d.ts +30 -0
  346. package/dist/theme/lab.js +46 -0
  347. package/dist/theme/library.d.ts +114 -0
  348. package/dist/theme/library.js +300 -0
  349. package/dist/theme/measure.d.ts +144 -0
  350. package/dist/theme/measure.js +145 -0
  351. package/dist/theme/palettes.d.ts +64 -0
  352. package/dist/theme/palettes.js +497 -0
  353. package/dist/theme/registry.d.ts +59 -0
  354. package/dist/theme/registry.js +60 -0
  355. package/dist/theme/separation.d.ts +177 -0
  356. package/dist/theme/separation.js +203 -0
  357. package/dist/theme/style-presets.d.ts +60 -0
  358. package/dist/theme/style-presets.js +124 -0
  359. package/dist/theme/theme.d.ts +253 -0
  360. package/dist/theme/theme.js +171 -0
  361. package/dist/tree/apply.d.ts +16 -0
  362. package/dist/tree/apply.js +104 -0
  363. package/dist/tree/builders.d.ts +19 -0
  364. package/dist/tree/builders.js +20 -0
  365. package/dist/tree/compare.d.ts +68 -0
  366. package/dist/tree/compare.js +75 -0
  367. package/dist/tree/configuration.d.ts +25 -0
  368. package/dist/tree/configuration.js +108 -0
  369. package/dist/tree/delta.d.ts +288 -0
  370. package/dist/tree/delta.js +88 -0
  371. package/dist/tree/errors.d.ts +69 -0
  372. package/dist/tree/errors.js +34 -0
  373. package/dist/tree/identity.d.ts +117 -0
  374. package/dist/tree/identity.js +145 -0
  375. package/dist/tree/index.d.ts +21 -0
  376. package/dist/tree/index.js +21 -0
  377. package/dist/tree/inverse.d.ts +24 -0
  378. package/dist/tree/inverse.js +112 -0
  379. package/dist/tree/mutation.d.ts +18 -0
  380. package/dist/tree/mutation.js +49 -0
  381. package/dist/tree/naming.d.ts +4 -0
  382. package/dist/tree/naming.js +35 -0
  383. package/dist/tree/navigation.d.ts +38 -0
  384. package/dist/tree/navigation.js +83 -0
  385. package/dist/tree/node.d.ts +103 -0
  386. package/dist/tree/node.js +46 -0
  387. package/dist/tree/outline.d.ts +28 -0
  388. package/dist/tree/outline.js +10 -0
  389. package/dist/tree/tree.d.ts +83 -0
  390. package/dist/tree/tree.js +62 -0
  391. package/dist/write/commit.d.ts +124 -0
  392. package/dist/write/commit.js +234 -0
  393. package/dist/write/held.d.ts +674 -0
  394. package/dist/write/held.js +185 -0
  395. package/dist/write/index.d.ts +11 -0
  396. package/dist/write/index.js +11 -0
  397. package/dist/write/liveness.d.ts +132 -0
  398. package/dist/write/liveness.js +91 -0
  399. package/dist/write/revert.d.ts +79 -0
  400. package/dist/write/revert.js +134 -0
  401. package/package.json +160 -0
@@ -0,0 +1,451 @@
1
+ import { NAMESPACED_ID_PATTERN, NODE_ID_PATTERN, TREE_ID_PATTERN } from "../grammar.js";
2
+ import { DISCLOSED_ATTRIBUTE } from "../render/disclosed.js";
3
+ import { LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE, } from "../render/editable.js";
4
+ import { err, ok } from "../result.js";
5
+ import { createSignalLedger } from "./ledger.js";
6
+ import { READER_SIGNAL_KINDS } from "./kinds.js";
7
+ import { mintViewKey } from "./view.js";
8
+ /**
9
+ * Broadcasting reader signals from a rendered Loom page.
10
+ *
11
+ * The browser half of the seam. Point it at the root element of a page rendered
12
+ * with `addressed: true` and it watches the nodes on that page, gathers what
13
+ * readers do with them, and delivers a batch every few seconds — as a DOM event
14
+ * anything on the page can listen for, and to a `send` function if the host
15
+ * gives one.
16
+ *
17
+ * **Off unless a host calls it.** The library renders no script and starts no
18
+ * observer on its own; a page that never calls this broadcasts nothing (0136).
19
+ *
20
+ * **Configured by the host, never by the tree.** Which kinds and which primitive
21
+ * types are broadcast is an argument here, not a prop a proposal could set — a
22
+ * model must not be able to switch measurement of readers on by writing a delta.
23
+ *
24
+ * **It reads the page, not the components.** Every fact it needs is already on
25
+ * the markup: identity from the addressed attributes, what a reader can aim at
26
+ * from the elements HTML gives targets, and a disclosure from the attribute the
27
+ * disclose control stamps. No primitive is instrumented, so no primitive can
28
+ * forget to be.
29
+ *
30
+ * **A press says which regions it was in.** A reader aims at a button, and a
31
+ * button is an addressed node of its own, so the node an `activated` names is
32
+ * the control rather than the band. The addressed elements above it go on the
33
+ * signal as `within`, read off the walk this was already doing — because which
34
+ * region a node sat in is a fact about the page at the moment of the press, and
35
+ * nothing downstream can recover it afterwards.
36
+ *
37
+ * **It keeps up with a page that changes.** Nodes that arrive after it started
38
+ * are watched and nodes that leave stop counting, so a band behind a Suspense
39
+ * boundary, a list that grows, and every region a proposal has just changed are
40
+ * measured like the rest. What it does *not* follow is the page becoming a
41
+ * different page: the tree and revision are read once, off the root, and every
42
+ * batch is filed under them. **A new root, or a new revision in the same root,
43
+ * is a new broadcast** — `stop()` the old one and start another, or a
44
+ * client-side navigation files its signals under the revision it left.
45
+ */
46
+ /** The DOM event a batch is dispatched as, on the root element. It bubbles. */
47
+ /**
48
+ * The delivery helper travels with this entry point rather than getting one of
49
+ * its own.
50
+ *
51
+ * `deliver.ts` imports nothing at runtime, so it costs the same bytes reached
52
+ * from here as it would through a door of its own — and a host who is starting
53
+ * a broadcaster in a browser bundle is exactly the host who needs a `send`. One
54
+ * import line for the two things that are always used together.
55
+ */
56
+ export { DEFAULT_READER_SIGNAL_PATH, deliverReaderSignals, } from "./deliver.js";
57
+ export const READER_SIGNALS_EVENT = "loom:signals";
58
+ /**
59
+ * What a reader can aim at, as HTML defines it. `summary` is left out on
60
+ * purpose: opening a `details` is reported as `disclosed`, and reporting the same
61
+ * click twice under two kinds would double-count the one thing a reader did.
62
+ */
63
+ const TARGET_SELECTOR = [
64
+ "a[href]",
65
+ "button",
66
+ "input",
67
+ "select",
68
+ "textarea",
69
+ '[role="button"]',
70
+ '[role="link"]',
71
+ ].join(",");
72
+ /**
73
+ * The host's `kinds` and `types`, as one question: is this kind of signal about
74
+ * this type of primitive wanted?
75
+ */
76
+ const selectionOf = (kinds, types) => {
77
+ const enabled = new Set(kinds ?? READER_SIGNAL_KINDS);
78
+ const allowed = new Map(types === undefined
79
+ ? []
80
+ : Array.isArray(types)
81
+ ? READER_SIGNAL_KINDS.map((kind) => [kind, new Set(types)])
82
+ : READER_SIGNAL_KINDS.flatMap((kind) => {
83
+ const listed = types[kind];
84
+ return listed === undefined ? [] : [[kind, new Set(listed)]];
85
+ }));
86
+ return (kind, type) => enabled.has(kind) && (allowed.get(kind)?.has(type) ?? true);
87
+ };
88
+ const DEFAULT_FLUSH_MS = 5000;
89
+ /**
90
+ * On screen means a reader could be reading it: at least half of the element is
91
+ * visible, or it fills at least 30% of the viewport. The second clause is not
92
+ * optional — the visible fraction of an element taller than the window can never
93
+ * reach one half, so a long section judged by the first alone is never viewed.
94
+ */
95
+ const isReadable = (entry) => {
96
+ if (!entry.isIntersecting)
97
+ return false;
98
+ const viewport = entry.rootBounds?.height ?? globalThis.innerHeight ?? 0;
99
+ const fills = viewport > 0 && entry.intersectionRect.height / viewport >= 0.3;
100
+ return entry.intersectionRatio >= 0.5 || fills;
101
+ };
102
+ const intersectionVisibility = (onChange) => {
103
+ const observer = new IntersectionObserver((entries) => onChange(entries.map((entry) => ({ target: entry.target, visible: isReadable(entry) }))), { threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1] });
104
+ return { observe: (element) => observer.observe(element), disconnect: () => observer.disconnect() };
105
+ };
106
+ /**
107
+ * Recognisers built from the id grammar rather than the schemas, so the
108
+ * broadcaster ships no schema library to the browser. The check is the same
109
+ * pattern the schemas apply; the brand is a claim that pattern earns.
110
+ */
111
+ const isNodeId = (value) => value !== null && NODE_ID_PATTERN.test(value);
112
+ const isTreeId = (value) => value !== null && TREE_ID_PATTERN.test(value);
113
+ const isPrimitiveType = (value) => value !== null && NAMESPACED_ID_PATTERN.test(value);
114
+ /** The identity an element carries, or `undefined` when it carries none worth trusting. */
115
+ const addressOf = (element) => {
116
+ const nodeId = element.getAttribute(LOOM_NODE_ATTRIBUTE);
117
+ const type = element.getAttribute(LOOM_TYPE_ATTRIBUTE);
118
+ return isNodeId(nodeId) && isPrimitiveType(type) ? { nodeId, type } : undefined;
119
+ };
120
+ const pageOf = (root) => {
121
+ const treeId = root.getAttribute(LOOM_TREE_ATTRIBUTE);
122
+ /**
123
+ * Matched as digits before it is converted. `Number(null)` and `Number("")` are
124
+ * both 0, so a page with no revision at all would otherwise pass as revision 0
125
+ * and every signal from it would be filed under a revision it never had.
126
+ */
127
+ const written = root.getAttribute(LOOM_REVISION_ATTRIBUTE) ?? "";
128
+ const revision = /^\d+$/.test(written) ? Number(written) : Number.NaN;
129
+ return isTreeId(treeId) && Number.isSafeInteger(revision)
130
+ ? ok({ treeId, revision })
131
+ : err({
132
+ code: "unaddressed",
133
+ detail: `the root element carries no ${LOOM_TREE_ATTRIBUTE} and ${LOOM_REVISION_ATTRIBUTE}; render the page with addressed: true`,
134
+ });
135
+ };
136
+ /** The nearest addressed element at or above `element`, without leaving the page. */
137
+ const nearestAddressed = (root, element) => {
138
+ const found = element.closest(`[${LOOM_NODE_ATTRIBUTE}]`);
139
+ return found !== null && root.contains(found) ? found : undefined;
140
+ };
141
+ /**
142
+ * The addressed elements above `element`, nearest first, stopping at the root.
143
+ *
144
+ * The same walk `nearestAddressed` already does, continued instead of stopped —
145
+ * so a press knows the card, the band and the page it was in rather than only
146
+ * the button, and nothing has to consult the tree afterwards to find out. The
147
+ * root itself is included when it is addressed, because a page whose root is a
148
+ * node is a region like any other.
149
+ *
150
+ * An element the walk cannot read an address off is skipped rather than ending
151
+ * the ancestry: `LOOM_NODE_ATTRIBUTE` without a readable type is markup this
152
+ * broadcaster does not trust, not a ceiling on what is above it.
153
+ */
154
+ const ancestryOf = (root, element) => {
155
+ const found = [];
156
+ for (let above = element.parentElement; above !== null && root.contains(above); above = above.parentElement) {
157
+ const address = addressOf(above);
158
+ if (address !== undefined)
159
+ found.push(address);
160
+ if (above === root)
161
+ break;
162
+ }
163
+ return found;
164
+ };
165
+ /** A sink observes; it does not get a vote (0042). Neither a throw nor a rejection reaches the page. */
166
+ const deliverSafely = (send, batch) => {
167
+ if (send === undefined)
168
+ return;
169
+ try {
170
+ const pending = send(batch);
171
+ if (pending instanceof Promise)
172
+ pending.catch(() => undefined);
173
+ }
174
+ catch {
175
+ // Contained by design.
176
+ }
177
+ };
178
+ /**
179
+ * Start broadcasting reader signals from the page under `root`.
180
+ *
181
+ * Returns an error rather than broadcasting nothing when the page is not
182
+ * addressed, because a silent broadcaster on an unaddressed page is exactly the
183
+ * misconfiguration nobody would notice.
184
+ *
185
+ * Nodes added under `root` afterwards are picked up and nodes removed stop
186
+ * counting. The tree and revision are not: they are read once, here, and a page
187
+ * that becomes a different page — a client-side navigation, a re-render at a new
188
+ * revision into the same root — needs `stop()` and a new broadcast, or its
189
+ * signals are filed under the revision it left.
190
+ */
191
+ export const broadcastReaderSignals = (root, options = {}) => {
192
+ const page = pageOf(root);
193
+ if (!page.ok)
194
+ return page;
195
+ const now = options.now ?? Date.now;
196
+ const wants = selectionOf(options.kinds, options.types);
197
+ const document = root.ownerDocument;
198
+ /**
199
+ * Minted once, here, and carried by every batch this broadcast sends — which
200
+ * is what makes the batches of one page view correlatable and two page views
201
+ * not (0146). A new broadcast is a new view, including the second one a
202
+ * client-side navigation needs, so the key cannot outlive the page it
203
+ * describes even by accident.
204
+ */
205
+ const view = mintViewKey(options.random);
206
+ const ledger = createSignalLedger(document.visibilityState === "hidden");
207
+ let stopped = false;
208
+ const walks = options.within ?? true;
209
+ /**
210
+ * What a delegated signal says about where it happened, as the fragment its
211
+ * factory spreads.
212
+ *
213
+ * An empty object rather than `within: []` when the host turned the walk off,
214
+ * because an empty ancestry is a claim — *this node has no addressed
215
+ * ancestor* — and a broadcaster that was told not to look has not made it.
216
+ */
217
+ const ancestry = (target) => walks ? { within: ancestryOf(root, target) } : {};
218
+ const record = (kind, signal) => (element) => {
219
+ const target = nearestAddressed(root, element);
220
+ if (target === undefined)
221
+ return;
222
+ const address = addressOf(target);
223
+ if (address === undefined || !wants(kind, address.type))
224
+ return;
225
+ ledger.noted(signal(address, ancestry(target)));
226
+ };
227
+ const flush = () => {
228
+ const drained = ledger.drain(now());
229
+ /**
230
+ * Viewed and dwelled are gathered together, because one observer serves both,
231
+ * and are selected here — so a host asking only for time on screen gets no
232
+ * `viewed`, and a type watched for one kind reports nothing for the other.
233
+ */
234
+ const signals = drained.filter((signal) => wants(signal.kind, signal.type));
235
+ if (signals.length === 0)
236
+ return;
237
+ const batch = {
238
+ treeId: page.value.treeId,
239
+ revision: page.value.revision,
240
+ sentAt: now(),
241
+ view,
242
+ signals,
243
+ };
244
+ root.dispatchEvent(new CustomEvent(READER_SIGNALS_EVENT, { detail: batch, bubbles: true }));
245
+ deliverSafely(options.send, batch);
246
+ };
247
+ const watched = (type) => wants("viewed", type) || wants("dwelled", type);
248
+ /**
249
+ * Each observed element's address, read once when observing starts. The
250
+ * observer calls back at every threshold an element crosses — eleven times on
251
+ * the way into view — and reading two attributes and testing two patterns on
252
+ * each of those is work whose answer cannot have changed.
253
+ */
254
+ const addresses = new WeakMap();
255
+ const enabled = options.kinds ?? READER_SIGNAL_KINDS;
256
+ const watchesTime = enabled.includes("viewed") || enabled.includes("dwelled");
257
+ const visibility = watchesTime
258
+ ? (options.observeVisibility ?? intersectionVisibility)((entries) => {
259
+ const at = now();
260
+ for (const entry of entries) {
261
+ const address = addresses.get(entry.target);
262
+ if (address === undefined)
263
+ continue;
264
+ if (entry.visible)
265
+ ledger.entered(address, at);
266
+ else
267
+ ledger.left(address.nodeId, at);
268
+ }
269
+ })
270
+ : undefined;
271
+ /** An element and every addressed element under it, which is what a subtree arriving or leaving amounts to. */
272
+ const addressedWithin = (element) => [
273
+ element,
274
+ ...Array.from(element.querySelectorAll(`[${LOOM_NODE_ATTRIBUTE}]`)),
275
+ ];
276
+ /** Hand an element to the visibility observer, if time on screen is wanted for what it is. */
277
+ const watchForTime = (element) => {
278
+ if (visibility === undefined)
279
+ return;
280
+ const address = addressOf(element);
281
+ if (address === undefined || !watched(address.type))
282
+ return;
283
+ addresses.set(element, address);
284
+ visibility.observe(element);
285
+ };
286
+ /**
287
+ * A node left the page, so the stretch it was in the middle of ends here.
288
+ *
289
+ * Closed on the mutation rather than left to the visibility observer: a
290
+ * removed element may never be reported as having gone out of view, and a
291
+ * stretch that is never closed is time a reader is credited with forever.
292
+ */
293
+ const departed = (element, at) => {
294
+ const address = addresses.get(element);
295
+ if (address !== undefined)
296
+ ledger.left(address.nodeId, at);
297
+ };
298
+ for (const element of addressedWithin(root))
299
+ watchForTime(element);
300
+ /**
301
+ * What the page grows and sheds after the broadcast started.
302
+ *
303
+ * `activated` and `disclosed` reach a node that did not exist yet on their
304
+ * own, because both are delegated from the root and read the nearest addressed
305
+ * element at the moment they happen. Time on screen is the one kind that needs
306
+ * each element handed to an observer, so a broadcaster that looked once
307
+ * reported nothing about anything rendered afterwards — a band behind a
308
+ * Suspense boundary, a region a client component mounts, a list that grows,
309
+ * **and every region a proposal has just changed.**
310
+ *
311
+ * That last one is why this is not a nicety. *Before versus after a change* is
312
+ * the measurement Loom exists to make, and it was the one measurement that did
313
+ * not work: an applied change renders after the broadcaster started, so every
314
+ * adapted region was invisible to `viewed` and `dwelled` while the rest of the
315
+ * page was counted normally. Numbers that understate only the changed bands
316
+ * are worse than no numbers, because they look like data.
317
+ *
318
+ * Only built when time is being watched at all: the other kinds need no help.
319
+ */
320
+ const arrivals = visibility === undefined
321
+ ? undefined
322
+ : new MutationObserver((mutations) => {
323
+ const at = now();
324
+ for (const mutation of mutations) {
325
+ for (const added of Array.from(mutation.addedNodes)) {
326
+ if (added instanceof Element)
327
+ for (const element of addressedWithin(added))
328
+ watchForTime(element);
329
+ }
330
+ for (const gone of Array.from(mutation.removedNodes)) {
331
+ if (gone instanceof Element)
332
+ for (const element of addressedWithin(gone))
333
+ departed(element, at);
334
+ }
335
+ }
336
+ });
337
+ const onActivated = record("activated", (address, within) => ({
338
+ kind: "activated",
339
+ ...address,
340
+ at: now(),
341
+ ...within,
342
+ }));
343
+ const onClick = (event) => {
344
+ const control = event.target instanceof Element ? event.target.closest(TARGET_SELECTOR) : null;
345
+ if (control === null || !root.contains(control))
346
+ return;
347
+ /** A disclose control reports as `disclosed`, for the same reason `summary` is left out above. */
348
+ if (control.hasAttribute(DISCLOSED_ATTRIBUTE))
349
+ return;
350
+ onActivated(control);
351
+ };
352
+ /**
353
+ * The last state each `details` was seen in, so only a change is reported.
354
+ *
355
+ * A browser fires `toggle` for a `details` that was *authored* open, as the
356
+ * page loads — nobody opened it. Snapshotting every one when broadcasting
357
+ * starts, and reporting a toggle only when it disagrees with the snapshot, is
358
+ * what keeps a page's own markup from reading as a reader's action. One added
359
+ * to the page later has no snapshot, and its first toggle is taken at its word.
360
+ */
361
+ const lastOpen = new WeakMap(Array.from(root.querySelectorAll("details")).map((details) => [details, details.open]));
362
+ const onToggle = (event) => {
363
+ const details = event.target;
364
+ if (!(details instanceof HTMLDetailsElement))
365
+ return;
366
+ if (lastOpen.get(details) === details.open)
367
+ return;
368
+ lastOpen.set(details, details.open);
369
+ record("disclosed", (address, within) => ({
370
+ kind: "disclosed",
371
+ ...address,
372
+ open: details.open,
373
+ at: now(),
374
+ ...within,
375
+ }))(details);
376
+ };
377
+ const disclosures = new MutationObserver((mutations) => {
378
+ for (const mutation of mutations) {
379
+ if (!(mutation.target instanceof Element))
380
+ continue;
381
+ const open = mutation.target.getAttribute(DISCLOSED_ATTRIBUTE);
382
+ const settled = open === "true" || open === "false";
383
+ if (!settled || mutation.oldValue === null || mutation.oldValue === open)
384
+ continue;
385
+ record("disclosed", (address, within) => ({
386
+ kind: "disclosed",
387
+ ...address,
388
+ open: open === "true",
389
+ at: now(),
390
+ ...within,
391
+ }))(mutation.target);
392
+ }
393
+ });
394
+ /**
395
+ * The batch timer runs only while the page is visible. A hidden page gathers
396
+ * nothing — the ledger has stopped counting — so a timer ticking in a
397
+ * background tab would wake the page every few seconds to find that out.
398
+ */
399
+ const flushEveryMs = options.flushEveryMs ?? DEFAULT_FLUSH_MS;
400
+ let timer;
401
+ const startTimer = () => {
402
+ if (timer === undefined)
403
+ timer = setInterval(flush, flushEveryMs);
404
+ };
405
+ const stopTimer = () => {
406
+ if (timer !== undefined)
407
+ clearInterval(timer);
408
+ timer = undefined;
409
+ };
410
+ const onVisibility = () => {
411
+ if (document.visibilityState === "hidden") {
412
+ ledger.hid(now());
413
+ flush();
414
+ stopTimer();
415
+ }
416
+ else {
417
+ ledger.showed(now());
418
+ startTimer();
419
+ }
420
+ };
421
+ const onPageHide = () => flush();
422
+ root.addEventListener("click", onClick);
423
+ root.addEventListener("toggle", onToggle, true);
424
+ disclosures.observe(root, {
425
+ attributes: true,
426
+ attributeFilter: [DISCLOSED_ATTRIBUTE],
427
+ attributeOldValue: true,
428
+ subtree: true,
429
+ });
430
+ arrivals?.observe(root, { childList: true, subtree: true });
431
+ document.addEventListener("visibilitychange", onVisibility);
432
+ document.defaultView?.addEventListener("pagehide", onPageHide);
433
+ if (document.visibilityState !== "hidden")
434
+ startTimer();
435
+ const stop = () => {
436
+ if (stopped)
437
+ return;
438
+ stopped = true;
439
+ flush();
440
+ stopTimer();
441
+ visibility?.disconnect();
442
+ disclosures.disconnect();
443
+ arrivals?.disconnect();
444
+ root.removeEventListener("click", onClick);
445
+ root.removeEventListener("toggle", onToggle, true);
446
+ document.removeEventListener("visibilitychange", onVisibility);
447
+ document.defaultView?.removeEventListener("pagehide", onPageHide);
448
+ };
449
+ return ok({ flush, stop });
450
+ };
451
+ //# sourceMappingURL=broadcast.js.map
@@ -0,0 +1,184 @@
1
+ import { z } from "zod";
2
+ import { type Clock } from "../runtime/events.js";
3
+ import type { ReaderSignalJournal, ReaderSignalStoreError, ReceivedBatch } from "./journal.js";
4
+ import { type FunnelPair } from "./rollup.js";
5
+ import type { ReaderTallyStore } from "./tally.js";
6
+ /**
7
+ * The one operation that empties the buffer.
8
+ *
9
+ * `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
10
+ * keep what the fold produced — and until this module existed nothing joined
11
+ * the three, so a deployment with signals switched on accumulated the largest
12
+ * table it owns and counted none of it.
13
+ *
14
+ * **Counting and forgetting are one call, and that is the design rather than a
15
+ * convenience.** A rollup reports *what this window added* (0147), so a batch
16
+ * counted twice is counted twice forever: there is no idempotence to fall back
17
+ * on and no way to notice afterwards, because the wrong number looks exactly
18
+ * like a busy afternoon. The only defence that does not need durable bookkeeping
19
+ * is for the set of batches rolled up and the set forgotten to be the same set,
20
+ * decided once, in one place. That is this file, and it is why there is no
21
+ * exported `applyReaderSignalRetention` beside it — a function that can forget
22
+ * without counting is the data-loss bug, and one that can count without
23
+ * forgetting is the double-count bug.
24
+ *
25
+ * Nothing schedules it, for the reason nothing schedules telemetry's retention
26
+ * or `auditSnapshot`: when a deployment forgets is an operational choice, and a
27
+ * framework that quietly deleted a host's data on a timer it chose would be
28
+ * making it. A host calls this from a cron route, a deploy hook, or by hand.
29
+ *
30
+ * **One run at a time, and the caller is what makes that true.** Two runs over
31
+ * the same ripe prefix both roll it up and both apply; applying is additive
32
+ * (0147), so the counters double and the buffer empties once, leaving nothing
33
+ * behind that could say what happened. Nothing here can prevent it — a journal
34
+ * and a store are two handles with no shared transaction between them — so
35
+ * serialising belongs to whatever schedules this. `apps/loom/scripts/
36
+ * signals-collect.ts` does it with a Postgres advisory lock, which is the
37
+ * cheapest thing that works for a cron that overruns its own interval.
38
+ */
39
+ /**
40
+ * The window is the age a batch reaches before it is counted and dropped, and
41
+ * it is two arguments pulling opposite ways.
42
+ *
43
+ * **Longer is more accurate.** `views` and `reached` count distinct page views,
44
+ * distinctness does not add up, and a page view whose batches straddle two
45
+ * windows is counted in both — the over-count 0147 accepts. `tally.ts` already
46
+ * states the remedy in its own words: *a deployment that wants the bound small
47
+ * makes the rollup window long relative to a page view.* This is that number.
48
+ *
49
+ * **Shorter is more anonymous.** The raw window is the entire mechanism by
50
+ * which a view key stops existing (0146). The key is opaque, random and
51
+ * correlates nothing outside the buffer, but it correlates that, and the
52
+ * argument for it rests on how briefly it lives.
53
+ *
54
+ * An hour is long against a page view and short against a day, which is why it
55
+ * is the default rather than a constant: rule 5 of `docs/signals.md` makes the
56
+ * number a deployment's.
57
+ */
58
+ export declare const DEFAULT_READER_SIGNAL_WINDOW_MS: number;
59
+ /**
60
+ * A minute, and the floor is not a style choice.
61
+ *
62
+ * Under a minute every page view straddles a boundary, so `views` stops being
63
+ * an approximation and becomes a count of flushes — a number about the network
64
+ * rather than about readers. It also refuses the ordinary way a window is
65
+ * written wrongly, which is a units mistake: `windowMs: 60` reads as an hour
66
+ * and means a minute and a tenth of a second.
67
+ */
68
+ export declare const MIN_READER_SIGNAL_WINDOW_MS: number;
69
+ export declare const readerSignalWindowSchema: z.ZodObject<{
70
+ windowMs: z.ZodNumber;
71
+ }, "strip", z.ZodTypeAny, {
72
+ windowMs: number;
73
+ }, {
74
+ windowMs: number;
75
+ }>;
76
+ export type ReaderSignalWindow = z.infer<typeof readerSignalWindowSchema>;
77
+ /**
78
+ * How much of the buffer one run will look at.
79
+ *
80
+ * Incremental for telemetry retention's reason: a first run against a buffer
81
+ * nothing has ever drained does a bounded amount of work and the next run does
82
+ * more, so the operation is safe to schedule without knowing how far behind it
83
+ * is. `more` on the outcome is how a caller learns there was another run's
84
+ * worth waiting.
85
+ */
86
+ export declare const DEFAULT_COLLECTION_SCAN = 5000;
87
+ export declare const MAX_COLLECTION_SCAN = 50000;
88
+ export type CollectionRequest = {
89
+ readonly windowMs?: number;
90
+ /**
91
+ * The funnels this deployment asks about. Absent means none — a pair is a
92
+ * question somebody wrote down, and rollup does not invent questions.
93
+ *
94
+ * A pair added later applies to windows collected after it, never to the ones
95
+ * already folded, because the batches those answers came from are gone. That
96
+ * is the price of aggregates being the durable artefact and it is worth
97
+ * knowing before a deployment waits a day for a number it will not get.
98
+ */
99
+ readonly pairs?: readonly FunnelPair[];
100
+ readonly clock?: Clock;
101
+ readonly scanLimit?: number;
102
+ };
103
+ /**
104
+ * What one run may take, as a pure function of batches and an instant.
105
+ *
106
+ * The cut is the **first** batch young enough to keep, not every old one: the
107
+ * buffer forgets a prefix or nothing, exactly as the journals do, because a
108
+ * hole would make `seq` — an opaque increasing position — start meaning
109
+ * something a reader could misread. `receivedAt` is what it measures, never
110
+ * `sentAt`, which is a number a page said.
111
+ */
112
+ export type CollectionPlan = {
113
+ /** Old enough to count, in ascending `seq`. */
114
+ readonly ripe: readonly ReceivedBatch[];
115
+ /** The position to forget below, once the counters are durable. `null` when nothing is ripe. */
116
+ readonly before: number | null;
117
+ /** Seen by this scan and too young. A floor rather than a total — the scan stops at the first. */
118
+ readonly waiting: number;
119
+ };
120
+ export declare const collectionPlanOf: (scanned: readonly ReceivedBatch[], horizon: string) => CollectionPlan;
121
+ export declare const horizonOf: (configured: ReaderSignalWindow, now: string) => string | null;
122
+ /** The half of the outcome a caller shows or logs, with nothing in it about a reader. */
123
+ export type CollectionSummary = {
124
+ readonly counted: number;
125
+ readonly tallies: number;
126
+ readonly funnels: number;
127
+ /** Distinct page views the window held. */
128
+ readonly views: number;
129
+ /**
130
+ * Batches that carried no view key, whose occurrences counted and whose views
131
+ * did not. A rate shown without saying which denominator it used is the
132
+ * failure mode here, so the number travels with the run that produced it.
133
+ */
134
+ readonly uncorrelated: number;
135
+ };
136
+ export type CollectionOutcome = {
137
+ readonly outcome: "collected";
138
+ readonly summary: CollectionSummary;
139
+ /** Rows the buffer removed. Below `counted` only if something else pruned first. */
140
+ readonly removed: number;
141
+ /** The scan filled its limit with ripe batches, so another run has work now. */
142
+ readonly more: boolean;
143
+ }
144
+ /** Nothing is old enough yet, which is the ordinary answer on a quiet deployment. */
145
+ | {
146
+ readonly outcome: "nothing-ripe";
147
+ readonly waiting: number;
148
+ }
149
+ /**
150
+ * The counters took the window and the buffer would not drop it.
151
+ *
152
+ * Its own outcome because it is the one state that gets worse if it is
153
+ * ignored: the batches are durable in the counters and still in the buffer,
154
+ * so the next run counts them again. An operator seeing this prunes below the
155
+ * reported position by hand, or fixes the buffer before the next run.
156
+ */
157
+ | {
158
+ readonly outcome: "counted-not-forgotten";
159
+ readonly summary: CollectionSummary;
160
+ readonly before: number;
161
+ readonly error: ReaderSignalStoreError;
162
+ }
163
+ /** The window was not usable. Nothing was read, counted or deleted. */
164
+ | {
165
+ readonly outcome: "refused";
166
+ readonly reason: string;
167
+ }
168
+ /** Read or write failed before anything became durable. Nothing was deleted. */
169
+ | {
170
+ readonly outcome: "unavailable";
171
+ readonly error: ReaderSignalStoreError;
172
+ };
173
+ /**
174
+ * Count a window of the buffer into the durable counters, then drop it.
175
+ *
176
+ * The order is the safe one and the reverse is a data-loss bug that looks like
177
+ * a feature working: aggregates first, the buffer second. What that leaves is
178
+ * `counted-not-forgotten`, which is visible and recoverable — the opposite
179
+ * order's failure is neither.
180
+ */
181
+ export declare const collectReaderSignals: (journal: ReaderSignalJournal, store: ReaderTallyStore, request?: CollectionRequest) => Promise<CollectionOutcome>;
182
+ /** One line for an operator, because an outcome nobody can read is one nobody acts on. */
183
+ export declare const describeCollection: (outcome: CollectionOutcome) => string;
184
+ //# sourceMappingURL=collect.d.ts.map