@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,196 @@
1
+ import { z } from "zod";
2
+ import { clampLimit } from "../paging.js";
3
+ import { systemClock } from "../runtime/events.js";
4
+ import { rollUp } from "./rollup.js";
5
+ /**
6
+ * The one operation that empties the buffer.
7
+ *
8
+ * `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
9
+ * keep what the fold produced — and until this module existed nothing joined
10
+ * the three, so a deployment with signals switched on accumulated the largest
11
+ * table it owns and counted none of it.
12
+ *
13
+ * **Counting and forgetting are one call, and that is the design rather than a
14
+ * convenience.** A rollup reports *what this window added* (0147), so a batch
15
+ * counted twice is counted twice forever: there is no idempotence to fall back
16
+ * on and no way to notice afterwards, because the wrong number looks exactly
17
+ * like a busy afternoon. The only defence that does not need durable bookkeeping
18
+ * is for the set of batches rolled up and the set forgotten to be the same set,
19
+ * decided once, in one place. That is this file, and it is why there is no
20
+ * exported `applyReaderSignalRetention` beside it — a function that can forget
21
+ * without counting is the data-loss bug, and one that can count without
22
+ * forgetting is the double-count bug.
23
+ *
24
+ * Nothing schedules it, for the reason nothing schedules telemetry's retention
25
+ * or `auditSnapshot`: when a deployment forgets is an operational choice, and a
26
+ * framework that quietly deleted a host's data on a timer it chose would be
27
+ * making it. A host calls this from a cron route, a deploy hook, or by hand.
28
+ *
29
+ * **One run at a time, and the caller is what makes that true.** Two runs over
30
+ * the same ripe prefix both roll it up and both apply; applying is additive
31
+ * (0147), so the counters double and the buffer empties once, leaving nothing
32
+ * behind that could say what happened. Nothing here can prevent it — a journal
33
+ * and a store are two handles with no shared transaction between them — so
34
+ * serialising belongs to whatever schedules this. `apps/loom/scripts/
35
+ * signals-collect.ts` does it with a Postgres advisory lock, which is the
36
+ * cheapest thing that works for a cron that overruns its own interval.
37
+ */
38
+ /**
39
+ * The window is the age a batch reaches before it is counted and dropped, and
40
+ * it is two arguments pulling opposite ways.
41
+ *
42
+ * **Longer is more accurate.** `views` and `reached` count distinct page views,
43
+ * distinctness does not add up, and a page view whose batches straddle two
44
+ * windows is counted in both — the over-count 0147 accepts. `tally.ts` already
45
+ * states the remedy in its own words: *a deployment that wants the bound small
46
+ * makes the rollup window long relative to a page view.* This is that number.
47
+ *
48
+ * **Shorter is more anonymous.** The raw window is the entire mechanism by
49
+ * which a view key stops existing (0146). The key is opaque, random and
50
+ * correlates nothing outside the buffer, but it correlates that, and the
51
+ * argument for it rests on how briefly it lives.
52
+ *
53
+ * An hour is long against a page view and short against a day, which is why it
54
+ * is the default rather than a constant: rule 5 of `docs/signals.md` makes the
55
+ * number a deployment's.
56
+ */
57
+ export const DEFAULT_READER_SIGNAL_WINDOW_MS = 60 * 60 * 1000;
58
+ /**
59
+ * A minute, and the floor is not a style choice.
60
+ *
61
+ * Under a minute every page view straddles a boundary, so `views` stops being
62
+ * an approximation and becomes a count of flushes — a number about the network
63
+ * rather than about readers. It also refuses the ordinary way a window is
64
+ * written wrongly, which is a units mistake: `windowMs: 60` reads as an hour
65
+ * and means a minute and a tenth of a second.
66
+ */
67
+ export const MIN_READER_SIGNAL_WINDOW_MS = 60 * 1000;
68
+ export const readerSignalWindowSchema = z.object({
69
+ windowMs: z.number().int().min(MIN_READER_SIGNAL_WINDOW_MS),
70
+ });
71
+ /**
72
+ * How much of the buffer one run will look at.
73
+ *
74
+ * Incremental for telemetry retention's reason: a first run against a buffer
75
+ * nothing has ever drained does a bounded amount of work and the next run does
76
+ * more, so the operation is safe to schedule without knowing how far behind it
77
+ * is. `more` on the outcome is how a caller learns there was another run's
78
+ * worth waiting.
79
+ */
80
+ export const DEFAULT_COLLECTION_SCAN = 5_000;
81
+ export const MAX_COLLECTION_SCAN = 50_000;
82
+ /** Read in pages like every other log walk (0026), so memory is bounded by the page. */
83
+ const SCAN_PAGE = 500;
84
+ export const collectionPlanOf = (scanned, horizon) => {
85
+ const ceiling = scanned.findIndex((batch) => batch.receivedAt >= horizon);
86
+ const ripe = ceiling === -1 ? scanned : scanned.slice(0, ceiling);
87
+ const last = ripe.at(-1);
88
+ return {
89
+ ripe,
90
+ before: last === undefined ? null : last.seq + 1,
91
+ waiting: scanned.length - ripe.length,
92
+ };
93
+ };
94
+ export const horizonOf = (configured, now) => {
95
+ const instant = Date.parse(now);
96
+ return Number.isFinite(instant) ? new Date(instant - configured.windowMs).toISOString() : null;
97
+ };
98
+ /**
99
+ * The oldest end of the buffer, forward, stopping at the horizon.
100
+ *
101
+ * Every batch from the horizon on is too young to count, and `collectionPlanOf`
102
+ * needs only the first of them to know where the ripe prefix ends — so reading
103
+ * further would be reading the busiest part of the table to throw it away.
104
+ */
105
+ const scanFrom = async (journal, horizon, scanLimit) => {
106
+ const collected = [];
107
+ let cursor;
108
+ while (collected.length < scanLimit) {
109
+ const page = await journal.read({
110
+ direction: "newer",
111
+ limit: Math.min(SCAN_PAGE, scanLimit - collected.length),
112
+ ...(cursor ? { cursor } : {}),
113
+ });
114
+ if (!page.ok)
115
+ return { ok: false, error: page.error };
116
+ collected.push(...page.value.batches);
117
+ if (page.value.batches.some((batch) => batch.receivedAt >= horizon)) {
118
+ return { ok: true, batches: collected, full: false };
119
+ }
120
+ if (page.value.newer === null)
121
+ return { ok: true, batches: collected, full: false };
122
+ cursor = page.value.newer;
123
+ }
124
+ return { ok: true, batches: collected, full: true };
125
+ };
126
+ /**
127
+ * Count a window of the buffer into the durable counters, then drop it.
128
+ *
129
+ * The order is the safe one and the reverse is a data-loss bug that looks like
130
+ * a feature working: aggregates first, the buffer second. What that leaves is
131
+ * `counted-not-forgotten`, which is visible and recoverable — the opposite
132
+ * order's failure is neither.
133
+ */
134
+ export const collectReaderSignals = async (journal, store, request = {}) => {
135
+ /** Named for what it is rather than `window`, which is a global this package's sibling touches. */
136
+ const configured = readerSignalWindowSchema.safeParse({
137
+ windowMs: request.windowMs ?? DEFAULT_READER_SIGNAL_WINDOW_MS,
138
+ });
139
+ if (!configured.success) {
140
+ return { outcome: "refused", reason: configured.error.issues[0]?.message ?? "invalid window" };
141
+ }
142
+ const now = (request.clock ?? systemClock).now();
143
+ const horizon = horizonOf(configured.data, now);
144
+ if (horizon === null)
145
+ return { outcome: "refused", reason: `the clock read "${now}"` };
146
+ const scanned = await scanFrom(journal, horizon, clampLimit(request.scanLimit, { fallback: DEFAULT_COLLECTION_SCAN, max: MAX_COLLECTION_SCAN }));
147
+ if (!scanned.ok)
148
+ return { outcome: "unavailable", error: scanned.error };
149
+ const plan = collectionPlanOf(scanned.batches, horizon);
150
+ if (plan.before === null)
151
+ return { outcome: "nothing-ripe", waiting: plan.waiting };
152
+ const rollup = rollUp(plan.ripe, { ...(request.pairs ? { pairs: request.pairs } : {}) });
153
+ const summary = {
154
+ counted: plan.ripe.length,
155
+ tallies: rollup.tallies.length,
156
+ funnels: rollup.funnels.length,
157
+ views: rollup.views,
158
+ uncorrelated: rollup.uncorrelated,
159
+ };
160
+ const applied = await store.apply(rollup, now);
161
+ if (!applied.ok)
162
+ return { outcome: "unavailable", error: applied.error };
163
+ const forgotten = await journal.forget({ before: plan.before });
164
+ if (!forgotten.ok) {
165
+ return {
166
+ outcome: "counted-not-forgotten",
167
+ summary,
168
+ before: plan.before,
169
+ error: forgotten.error,
170
+ };
171
+ }
172
+ return {
173
+ outcome: "collected",
174
+ summary,
175
+ removed: forgotten.value.removed,
176
+ more: scanned.full,
177
+ };
178
+ };
179
+ const batches = (count) => `${count} ${count === 1 ? "batch" : "batches"}`;
180
+ const uncorrelated = (summary) => summary.uncorrelated === 0 ? "" : `, ${summary.uncorrelated} with no view key`;
181
+ /** One line for an operator, because an outcome nobody can read is one nobody acts on. */
182
+ export const describeCollection = (outcome) => {
183
+ switch (outcome.outcome) {
184
+ case "collected":
185
+ return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}, and forgot ${outcome.removed}${outcome.more ? " — more is waiting" : ""}`;
186
+ case "nothing-ripe":
187
+ return `nothing old enough to count${outcome.waiting === 0 ? "" : `, ${batches(outcome.waiting)} waiting`}`;
188
+ case "counted-not-forgotten":
189
+ return `counted ${batches(outcome.summary.counted)} and could not forget them, so the next run counts them again unless the buffer is pruned below ${outcome.before}: ${outcome.error.detail}`;
190
+ case "refused":
191
+ return `collection refused: ${outcome.reason}`;
192
+ case "unavailable":
193
+ return `collection could not run: ${outcome.error.detail}`;
194
+ }
195
+ };
196
+ //# sourceMappingURL=collect.js.map
@@ -0,0 +1,64 @@
1
+ import type { ReaderSignalBatch } from "./signal.js";
2
+ /**
3
+ * Getting a batch off the page.
4
+ *
5
+ * `broadcastReaderSignals` takes a `send` and does not care what it does, which
6
+ * is right — a sink observes and does not get a vote (0042), and a broadcaster
7
+ * that knew about URLs would be a broadcaster a test had to stub a network for.
8
+ * What that leaves is every host writing the same fifteen lines, and the two
9
+ * that exist in this repository are both written for a page that draws the
10
+ * batch rather than posts it. This is the `send` for the ordinary case.
11
+ *
12
+ * **It imports nothing at runtime.** The batch arrives as a type, which is
13
+ * erased, so this module costs a browser bundle its own bytes and no schema —
14
+ * the same property `view.ts` has and for the same reason (0136).
15
+ *
16
+ * **`sendBeacon` first, `fetch` second, and neither ever throws.** A beacon
17
+ * survives the page being closed, which is exactly when the last batch of a
18
+ * page view is sent and exactly when a `fetch` is cancelled. It can also refuse
19
+ * — the browser caps what it will hold in flight — and a refusal is reported by
20
+ * a `false` return rather than an exception, which is easy to write past. When
21
+ * it refuses, the batch is worth one `fetch` with `keepalive`, which is the
22
+ * same guarantee by another road.
23
+ */
24
+ /**
25
+ * Where a delivery goes when the host has no opinion.
26
+ *
27
+ * A path rather than a URL, and relative, so it is same-origin by construction.
28
+ * That is not only tidiness: `sendBeacon` cannot preflight, so a cross-origin
29
+ * beacon carrying `application/json` is refused by the browser before it is
30
+ * sent. A deployment that wants to collect signals on another origin has to
31
+ * serve CORS from it and will find out here.
32
+ *
33
+ * It is a default and not a constant the receiver shares. The endpoint's
34
+ * address is a deployment's choice — a host may serve it anywhere, and this is
35
+ * what the host who does not care gets.
36
+ */
37
+ export declare const DEFAULT_READER_SIGNAL_PATH = "/api/reader-signals";
38
+ /** `navigator.sendBeacon`, narrowed to what this uses. `false` means it would not take it. */
39
+ export type SendBeacon = (url: string, body: Blob) => boolean;
40
+ /** The fallback. Called only when a beacon was unavailable or refused the batch. */
41
+ export type PostBatch = (url: string, body: string) => void;
42
+ export type DeliverOptions = {
43
+ /** Where to post. {@link DEFAULT_READER_SIGNAL_PATH} when absent. */
44
+ readonly url?: string;
45
+ /** The browser's, when absent. A test passes its own. */
46
+ readonly beacon?: SendBeacon | null;
47
+ /** `fetch` with `keepalive`, when absent. */
48
+ readonly post?: PostBatch;
49
+ };
50
+ /**
51
+ * A `send` for `broadcastReaderSignals` that posts each batch.
52
+ *
53
+ * ```ts
54
+ * broadcastReaderSignals(root, { send: deliverReaderSignals() })
55
+ * ```
56
+ *
57
+ * Nothing about the response is read, and nothing about it could be useful: the
58
+ * page has no retry to attempt and no reader to tell. A refused batch is a
59
+ * counter that will not be incremented, which is the correct failure for a
60
+ * sink — the alternative is a page whose behaviour depends on whether anybody
61
+ * is measuring it.
62
+ */
63
+ export declare const deliverReaderSignals: (options?: DeliverOptions) => ((batch: ReaderSignalBatch) => void);
64
+ //# sourceMappingURL=deliver.d.ts.map
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Getting a batch off the page.
3
+ *
4
+ * `broadcastReaderSignals` takes a `send` and does not care what it does, which
5
+ * is right — a sink observes and does not get a vote (0042), and a broadcaster
6
+ * that knew about URLs would be a broadcaster a test had to stub a network for.
7
+ * What that leaves is every host writing the same fifteen lines, and the two
8
+ * that exist in this repository are both written for a page that draws the
9
+ * batch rather than posts it. This is the `send` for the ordinary case.
10
+ *
11
+ * **It imports nothing at runtime.** The batch arrives as a type, which is
12
+ * erased, so this module costs a browser bundle its own bytes and no schema —
13
+ * the same property `view.ts` has and for the same reason (0136).
14
+ *
15
+ * **`sendBeacon` first, `fetch` second, and neither ever throws.** A beacon
16
+ * survives the page being closed, which is exactly when the last batch of a
17
+ * page view is sent and exactly when a `fetch` is cancelled. It can also refuse
18
+ * — the browser caps what it will hold in flight — and a refusal is reported by
19
+ * a `false` return rather than an exception, which is easy to write past. When
20
+ * it refuses, the batch is worth one `fetch` with `keepalive`, which is the
21
+ * same guarantee by another road.
22
+ */
23
+ /**
24
+ * Where a delivery goes when the host has no opinion.
25
+ *
26
+ * A path rather than a URL, and relative, so it is same-origin by construction.
27
+ * That is not only tidiness: `sendBeacon` cannot preflight, so a cross-origin
28
+ * beacon carrying `application/json` is refused by the browser before it is
29
+ * sent. A deployment that wants to collect signals on another origin has to
30
+ * serve CORS from it and will find out here.
31
+ *
32
+ * It is a default and not a constant the receiver shares. The endpoint's
33
+ * address is a deployment's choice — a host may serve it anywhere, and this is
34
+ * what the host who does not care gets.
35
+ */
36
+ export const DEFAULT_READER_SIGNAL_PATH = "/api/reader-signals";
37
+ const browserBeacon = () => {
38
+ const sender = globalThis.navigator;
39
+ return typeof sender?.sendBeacon === "function" ? (url, body) => sender.sendBeacon(url, body) : null;
40
+ };
41
+ /**
42
+ * `keepalive` is what makes this survive the page it was sent from. Rejections
43
+ * are swallowed here rather than left to the broadcaster's containment, so that
44
+ * a host calling this directly gets the same promise the broadcaster does.
45
+ */
46
+ const fetchPost = (url, body) => {
47
+ void globalThis
48
+ .fetch(url, {
49
+ method: "POST",
50
+ keepalive: true,
51
+ headers: { "content-type": "application/json" },
52
+ body,
53
+ })
54
+ .catch(() => undefined);
55
+ };
56
+ /**
57
+ * A `send` for `broadcastReaderSignals` that posts each batch.
58
+ *
59
+ * ```ts
60
+ * broadcastReaderSignals(root, { send: deliverReaderSignals() })
61
+ * ```
62
+ *
63
+ * Nothing about the response is read, and nothing about it could be useful: the
64
+ * page has no retry to attempt and no reader to tell. A refused batch is a
65
+ * counter that will not be incremented, which is the correct failure for a
66
+ * sink — the alternative is a page whose behaviour depends on whether anybody
67
+ * is measuring it.
68
+ */
69
+ export const deliverReaderSignals = (options = {}) => {
70
+ const url = options.url ?? DEFAULT_READER_SIGNAL_PATH;
71
+ const post = options.post ?? fetchPost;
72
+ return (batch) => {
73
+ const body = JSON.stringify(batch);
74
+ try {
75
+ const beacon = options.beacon === undefined ? browserBeacon() : options.beacon;
76
+ if (beacon !== null && beacon(url, new Blob([body], { type: "application/json" })))
77
+ return;
78
+ post(url, body);
79
+ }
80
+ catch {
81
+ // A sink does not get a vote (0042).
82
+ }
83
+ };
84
+ };
85
+ //# sourceMappingURL=deliver.js.map
@@ -0,0 +1,112 @@
1
+ import type { NodeId } from "../ids.js";
2
+ import type { PrimitiveType } from "../primitive-type.js";
3
+ import type { ReaderSignalBatch } from "./signal.js";
4
+ /**
5
+ * Batches folded into what a node was read like: time on screen, whether it was
6
+ * reached, what readers did in it.
7
+ *
8
+ * This is the live arithmetic — one accumulator, fed a batch at a time, held by
9
+ * whatever is watching. `rollup.ts` answers the other question, *what happened
10
+ * across many views*, and the two are separate because they have different
11
+ * inputs: a fold sees the batches of one page as they arrive and knows nothing
12
+ * about views, while rollup sees a window of stored batches from many views and
13
+ * cannot be fed one at a time.
14
+ *
15
+ * It exists as a framework module because it had already been written twice —
16
+ * `prototypes/ski-apparel/readings.mjs` is the working reference, and the
17
+ * portal's view and any demo rail would each have grown their own. Arithmetic
18
+ * rendered twice is arithmetic that drifts, and the version that drifts is
19
+ * always the one nobody is looking at.
20
+ *
21
+ * **Labels are not here.** The prototype's fold also turns node ids into
22
+ * section names and builds a feed of lines, using a legend that only that page
23
+ * has. Naming a node is a property of the page, not of the signals, so it stays
24
+ * with whoever has the legend. What is left is the part that is the same
25
+ * everywhere.
26
+ *
27
+ * Pure, and safe in a browser: no package, no schema, no clock.
28
+ */
29
+ /**
30
+ * What a set of batches says about each node they mention.
31
+ *
32
+ * Keyed by node id rather than held as a list because folding is a hot path in
33
+ * a page that is still being read — a list would be a scan per signal, and the
34
+ * ledger this replaces was quadratic once already.
35
+ */
36
+ export type ReaderReadings = {
37
+ /** Total time on screen. Summed across batches, because `dwelled` is per-batch. */
38
+ readonly dwellMs: Readonly<Record<NodeId, number>>;
39
+ /** Nodes that came into view at all. `viewed` fires once per node per page view. */
40
+ readonly reached: Readonly<Record<NodeId, true>>;
41
+ /**
42
+ * Times the node itself was used — a link followed, a button pressed, a field
43
+ * filled.
44
+ *
45
+ * It is the node the signal names, which is the nearest addressed element to
46
+ * what a reader aimed at. In the starter library that is the control, so a
47
+ * band's count here is zero however busy the band was; `engagements` is the
48
+ * number that is about the band.
49
+ */
50
+ readonly activations: Readonly<Record<NodeId, number>>;
51
+ readonly opens: Readonly<Record<NodeId, number>>;
52
+ readonly closes: Readonly<Record<NodeId, number>>;
53
+ /**
54
+ * Times a reader used something *inside* the node — pressed, followed, filled,
55
+ * opened or closed, at any depth.
56
+ *
57
+ * The regions' number. Read off the ancestry a delegated signal carries, so a
58
+ * batch whose senders did not walk contributes nothing rather than a guess.
59
+ * Strictly inside, so a control's own use is in `activations` and never here,
60
+ * and a subtree total is the addition.
61
+ *
62
+ * Occurrences rather than readers, because a fold is one page view: *how many
63
+ * of the people reading this used something in the band* is a question about
64
+ * many views, and it is `ReaderTally.engaged`.
65
+ */
66
+ readonly engagements: Readonly<Record<NodeId, number>>;
67
+ /**
68
+ * What each node is, as its signals reported it. Kept because a consumer
69
+ * holding only readings would otherwise have to go back to the tree to render
70
+ * a row, and the signals already say.
71
+ *
72
+ * A region named only as somewhere a press happened inside is in here too, so
73
+ * it gets a row rather than being a number with no name.
74
+ */
75
+ readonly types: Readonly<Record<NodeId, PrimitiveType>>;
76
+ readonly batches: number;
77
+ readonly signals: number;
78
+ };
79
+ export declare const EMPTY_READINGS: ReaderReadings;
80
+ /**
81
+ * One more batch, folded in.
82
+ *
83
+ * The batch's tree and revision are not checked against anything, because a
84
+ * reading is about one page and the caller is the one holding it. Folding two
85
+ * revisions into one accumulator is a caller's mistake and it is the caller who
86
+ * can see it — `rollup.ts` is the module that keeps revisions apart, because it
87
+ * is the one that is handed a mixture.
88
+ */
89
+ export declare const foldReaderSignals: (readings: ReaderReadings, batch: ReaderSignalBatch) => ReaderReadings;
90
+ export declare const readingsOf: (batches: readonly ReaderSignalBatch[]) => ReaderReadings;
91
+ /** One node's line, as something rendering a table wants it. */
92
+ export type NodeReading = {
93
+ readonly nodeId: NodeId;
94
+ readonly type: PrimitiveType;
95
+ readonly dwellMs: number;
96
+ readonly reached: boolean;
97
+ readonly activations: number;
98
+ readonly opens: number;
99
+ readonly closes: number;
100
+ /** Times a reader used something inside it, at any depth. */
101
+ readonly engagements: number;
102
+ };
103
+ /**
104
+ * Readings as rows, longest on screen first.
105
+ *
106
+ * The order is a default rather than a claim: a caller with a legend almost
107
+ * always wants the page's own order instead, which it can produce because every
108
+ * row names its node. What a caller without one wants is the interesting end
109
+ * first.
110
+ */
111
+ export declare const nodeReadingsOf: (readings: ReaderReadings) => readonly NodeReading[];
112
+ //# sourceMappingURL=fold.d.ts.map
@@ -0,0 +1,76 @@
1
+ export const EMPTY_READINGS = {
2
+ dwellMs: {},
3
+ reached: {},
4
+ activations: {},
5
+ opens: {},
6
+ closes: {},
7
+ engagements: {},
8
+ types: {},
9
+ batches: 0,
10
+ signals: 0,
11
+ };
12
+ const bumped = (counts, nodeId, by) => ({ ...counts, [nodeId]: (counts[nodeId] ?? 0) + by });
13
+ /**
14
+ * The regions a delegated signal says it happened inside, and their types, which
15
+ * a reading knows exactly as it knows the node's own.
16
+ */
17
+ const withinOf = (signal) => (signal.kind === "activated" || signal.kind === "disclosed") && signal.within !== undefined
18
+ ? signal.within
19
+ : [];
20
+ /** Every node a signal mentions is one this reading now knows the type of. */
21
+ const foldSignal = (readings, signal) => {
22
+ const { nodeId } = signal;
23
+ const within = withinOf(signal);
24
+ return {
25
+ ...readings,
26
+ engagements: within.reduce((counts, region) => bumped(counts, region.nodeId, 1), readings.engagements),
27
+ dwellMs: signal.kind === "dwelled" ? bumped(readings.dwellMs, nodeId, signal.ms) : readings.dwellMs,
28
+ reached: signal.kind === "viewed" ? { ...readings.reached, [nodeId]: true } : readings.reached,
29
+ activations: signal.kind === "activated" ? bumped(readings.activations, nodeId, 1) : readings.activations,
30
+ opens: signal.kind === "disclosed" && signal.open ? bumped(readings.opens, nodeId, 1) : readings.opens,
31
+ closes: signal.kind === "disclosed" && !signal.open ? bumped(readings.closes, nodeId, 1) : readings.closes,
32
+ types: {
33
+ ...readings.types,
34
+ ...Object.fromEntries(within.map((region) => [region.nodeId, region.type])),
35
+ [nodeId]: signal.type,
36
+ },
37
+ };
38
+ };
39
+ /**
40
+ * One more batch, folded in.
41
+ *
42
+ * The batch's tree and revision are not checked against anything, because a
43
+ * reading is about one page and the caller is the one holding it. Folding two
44
+ * revisions into one accumulator is a caller's mistake and it is the caller who
45
+ * can see it — `rollup.ts` is the module that keeps revisions apart, because it
46
+ * is the one that is handed a mixture.
47
+ */
48
+ export const foldReaderSignals = (readings, batch) => {
49
+ const folded = batch.signals.reduce(foldSignal, readings);
50
+ return { ...folded, batches: readings.batches + 1, signals: readings.signals + batch.signals.length };
51
+ };
52
+ export const readingsOf = (batches) => batches.reduce(foldReaderSignals, EMPTY_READINGS);
53
+ /**
54
+ * Readings as rows, longest on screen first.
55
+ *
56
+ * The order is a default rather than a claim: a caller with a legend almost
57
+ * always wants the page's own order instead, which it can produce because every
58
+ * row names its node. What a caller without one wants is the interesting end
59
+ * first.
60
+ */
61
+ export const nodeReadingsOf = (readings) => Object.keys(readings.types)
62
+ .map((key) => {
63
+ const nodeId = key;
64
+ return {
65
+ nodeId,
66
+ type: readings.types[nodeId],
67
+ dwellMs: readings.dwellMs[nodeId] ?? 0,
68
+ reached: readings.reached[nodeId] === true,
69
+ activations: readings.activations[nodeId] ?? 0,
70
+ opens: readings.opens[nodeId] ?? 0,
71
+ closes: readings.closes[nodeId] ?? 0,
72
+ engagements: readings.engagements[nodeId] ?? 0,
73
+ };
74
+ })
75
+ .sort((first, second) => second.dwellMs - first.dwellMs);
76
+ //# sourceMappingURL=fold.js.map
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Reader signals: what a published page may say about how it is being read,
3
+ * and what a deployment does with it once it has been said.
4
+ *
5
+ * The vocabulary and its parser are safe to import anywhere. The broadcaster
6
+ * touches the DOM only when it is called, so this entry point also loads on a
7
+ * server that merely parses batches (0136).
8
+ *
9
+ * **In a browser bundle, import the broadcaster from
10
+ * `@jam-overture/loom/signals/broadcast` instead.** This entry also carries the
11
+ * schemas, and a bundler cannot leave the schema library out once it is
12
+ * imported — about 60 KB of it, against a broadcaster of about 5 KB.
13
+ *
14
+ * **Postgres is not re-exported here.** It reaches Drizzle and a database
15
+ * driver, and a route handler that only ingests should not load either;
16
+ * `@jam-overture/loom/signals/postgres` is where a deployment picks it up, exactly
17
+ * as the store and the journal do it.
18
+ */
19
+ export * from "./broadcast.js";
20
+ export * from "./collect.js";
21
+ export * from "./deliver.js";
22
+ export * from "./fold.js";
23
+ export * from "./ingest.js";
24
+ export * from "./intake.js";
25
+ export * from "./journal.js";
26
+ export * from "./memory.js";
27
+ export * from "./rollup.js";
28
+ export * from "./signal.js";
29
+ export * from "./tally.js";
30
+ export * from "./view.js";
31
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Reader signals: what a published page may say about how it is being read,
3
+ * and what a deployment does with it once it has been said.
4
+ *
5
+ * The vocabulary and its parser are safe to import anywhere. The broadcaster
6
+ * touches the DOM only when it is called, so this entry point also loads on a
7
+ * server that merely parses batches (0136).
8
+ *
9
+ * **In a browser bundle, import the broadcaster from
10
+ * `@jam-overture/loom/signals/broadcast` instead.** This entry also carries the
11
+ * schemas, and a bundler cannot leave the schema library out once it is
12
+ * imported — about 60 KB of it, against a broadcaster of about 5 KB.
13
+ *
14
+ * **Postgres is not re-exported here.** It reaches Drizzle and a database
15
+ * driver, and a route handler that only ingests should not load either;
16
+ * `@jam-overture/loom/signals/postgres` is where a deployment picks it up, exactly
17
+ * as the store and the journal do it.
18
+ */
19
+ export * from "./broadcast.js";
20
+ export * from "./collect.js";
21
+ export * from "./deliver.js";
22
+ export * from "./fold.js";
23
+ export * from "./ingest.js";
24
+ export * from "./intake.js";
25
+ export * from "./journal.js";
26
+ export * from "./memory.js";
27
+ export * from "./rollup.js";
28
+ export * from "./signal.js";
29
+ export * from "./tally.js";
30
+ export * from "./view.js";
31
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,51 @@
1
+ import { type Result } from "../result.js";
2
+ import type { ReaderSignalJournal, ReaderSignalStoreError } from "./journal.js";
3
+ import { type ReaderSignalParseError } from "./signal.js";
4
+ /**
5
+ * The doorway a browser's batches come through.
6
+ *
7
+ * A page is not a trusted author. Everything that arrives here is parsed before
8
+ * it is kept — the shape, the kinds, the tree id's grammar, and the view key's
9
+ * thirty-two characters of nothing — because the alternative is a database
10
+ * column a visitor can write anything into, including the visitor id that 0146
11
+ * exists to refuse.
12
+ *
13
+ * The route handler that serves this is a surface's, not the framework's. What
14
+ * the framework owns is this function: unknown in, a counted outcome or a
15
+ * typed refusal out, no throw either way.
16
+ */
17
+ /**
18
+ * How many batches one delivery may carry.
19
+ *
20
+ * A broadcaster sends one at a time, so anything above a handful is a retry
21
+ * queue draining after an outage, and that is worth allowing. What it is not
22
+ * worth is unbounded: the parse is the expensive part and an endpoint that will
23
+ * parse as many batches as a body can hold is an endpoint that can be made to
24
+ * spend a minute on one request.
25
+ */
26
+ export declare const MAX_BATCHES_PER_DELIVERY = 50;
27
+ export type IngestOutcome = {
28
+ readonly batches: number;
29
+ readonly signals: number;
30
+ };
31
+ export type IngestError = {
32
+ readonly code: "invalid-delivery";
33
+ /** Which batch of the delivery, so a sender with one bad batch can be told which. */
34
+ readonly index: number;
35
+ readonly issues: ReaderSignalParseError["issues"];
36
+ } | {
37
+ readonly code: "too-many";
38
+ readonly limit: number;
39
+ readonly given: number;
40
+ } | ReaderSignalStoreError;
41
+ export declare const describeIngestError: (error: IngestError) => string;
42
+ /**
43
+ * Parse a delivery and keep it.
44
+ *
45
+ * **Nothing is kept unless all of it parses.** A partial accept would mean a
46
+ * sender's retry either duplicates what was taken or drops what was not, and
47
+ * neither is something a browser can be asked to work out. It also means the
48
+ * refusal is actionable: one index, one reason.
49
+ */
50
+ export declare const ingestReaderSignals: (journal: ReaderSignalJournal, input: unknown) => Promise<Result<IngestOutcome, IngestError>>;
51
+ //# sourceMappingURL=ingest.d.ts.map