@jam-overture/loom 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (414) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/audience/compose.d.ts +112 -0
  11. package/dist/audience/compose.js +134 -0
  12. package/dist/audience/memory.d.ts +14 -0
  13. package/dist/audience/memory.js +71 -0
  14. package/dist/audience/overlay-store.d.ts +343 -0
  15. package/dist/audience/overlay-store.js +217 -0
  16. package/dist/audience/rule.d.ts +121 -0
  17. package/dist/audience/rule.js +78 -0
  18. package/dist/cli/index.d.ts +3 -4
  19. package/dist/cli/index.js +3 -4
  20. package/dist/cli/templates.js +19 -0
  21. package/dist/data/adapter.d.ts +9 -1
  22. package/dist/data/adapter.js +2 -0
  23. package/dist/data/plan.js +0 -0
  24. package/dist/data/resolution.d.ts +23 -1
  25. package/dist/data/resolve.d.ts +31 -4
  26. package/dist/data/resolve.js +11 -3
  27. package/dist/ids.d.ts +10 -0
  28. package/dist/ids.js +11 -1
  29. package/dist/index.d.ts +1 -0
  30. package/dist/index.js +1 -0
  31. package/dist/interpretation/anthropic.d.ts +1 -1
  32. package/dist/interpretation/anthropic.js +2 -22
  33. package/dist/interpretation/client.d.ts +1 -1
  34. package/dist/interpretation/materialize.js +67 -22
  35. package/dist/interpretation/openai-compatible.d.ts +36 -0
  36. package/dist/interpretation/openai-compatible.js +79 -0
  37. package/dist/interpretation/status.d.ts +19 -0
  38. package/dist/interpretation/status.js +26 -0
  39. package/dist/live/index.d.ts +73 -0
  40. package/dist/live/index.js +73 -0
  41. package/dist/live/pages.d.ts +187 -0
  42. package/dist/live/pages.js +161 -0
  43. package/dist/live/pull.d.ts +147 -0
  44. package/dist/live/pull.js +398 -0
  45. package/dist/live/pulling.d.ts +79 -0
  46. package/dist/live/pulling.js +117 -0
  47. package/dist/live/window.d.ts +129 -0
  48. package/dist/live/window.js +132 -0
  49. package/dist/patch.d.ts +54 -0
  50. package/dist/patch.js +44 -0
  51. package/dist/project/closing.d.ts +51 -0
  52. package/dist/project/closing.js +53 -0
  53. package/dist/project/memory.d.ts +20 -0
  54. package/dist/project/memory.js +97 -0
  55. package/dist/project/project.d.ts +90 -0
  56. package/dist/project/project.js +91 -0
  57. package/dist/project/store.d.ts +135 -0
  58. package/dist/project/store.js +41 -0
  59. package/dist/registered.d.ts +64 -0
  60. package/dist/registered.js +118 -0
  61. package/dist/render/addressed.d.ts +35 -0
  62. package/dist/render/addressed.js +79 -0
  63. package/dist/render/behaviour-adjust.d.ts +11 -19
  64. package/dist/render/behaviour-adjust.js +75 -21
  65. package/dist/render/behaviour-present.d.ts +8 -0
  66. package/dist/render/behaviour-present.js +57 -6
  67. package/dist/render/behaviour.d.ts +98 -17
  68. package/dist/render/behaviour.js +91 -26
  69. package/dist/render/control-name.d.ts +68 -0
  70. package/dist/render/control-name.js +37 -0
  71. package/dist/render/diagnostics.d.ts +72 -0
  72. package/dist/render/diagnostics.js +7 -0
  73. package/dist/render/document-theme.d.ts +70 -0
  74. package/dist/render/document-theme.js +139 -0
  75. package/dist/render/editable.d.ts +15 -1
  76. package/dist/render/editable.js +13 -1
  77. package/dist/render/expected.d.ts +98 -0
  78. package/dist/render/expected.js +88 -0
  79. package/dist/render/index.d.ts +4 -0
  80. package/dist/render/index.js +4 -0
  81. package/dist/render/reads.d.ts +11 -0
  82. package/dist/render/reads.js +12 -1
  83. package/dist/render/render.d.ts +11 -0
  84. package/dist/render/render.js +294 -53
  85. package/dist/render/request.d.ts +8 -1
  86. package/dist/render/request.js +1 -0
  87. package/dist/render/slots.d.ts +52 -0
  88. package/dist/render/slots.js +24 -0
  89. package/dist/render/theme.d.ts +54 -1
  90. package/dist/render/theme.js +23 -1
  91. package/dist/render/unshown.d.ts +152 -0
  92. package/dist/render/unshown.js +80 -0
  93. package/dist/runtime/analysis.d.ts +94 -9
  94. package/dist/runtime/analysis.js +54 -9
  95. package/dist/runtime/assessment.d.ts +36 -2
  96. package/dist/runtime/assessment.js +27 -2
  97. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  98. package/dist/runtime/auto-apply-ceiling.js +66 -0
  99. package/dist/runtime/checks.d.ts +148 -0
  100. package/dist/runtime/checks.js +112 -0
  101. package/dist/runtime/disposition.d.ts +96 -0
  102. package/dist/runtime/disposition.js +46 -0
  103. package/dist/runtime/gate.js +91 -10
  104. package/dist/runtime/index.d.ts +4 -0
  105. package/dist/runtime/index.js +4 -0
  106. package/dist/runtime/irreversibility.d.ts +64 -0
  107. package/dist/runtime/irreversibility.js +45 -0
  108. package/dist/runtime/nesting.d.ts +13 -1
  109. package/dist/runtime/nesting.js +41 -24
  110. package/dist/runtime/pipeline.d.ts +43 -0
  111. package/dist/runtime/pipeline.js +10 -2
  112. package/dist/runtime/policy-change.d.ts +93 -0
  113. package/dist/runtime/policy-change.js +305 -0
  114. package/dist/runtime/policy-log.d.ts +406 -0
  115. package/dist/runtime/policy-log.js +285 -0
  116. package/dist/runtime/policy.d.ts +8 -6
  117. package/dist/runtime/policy.js +5 -2
  118. package/dist/runtime/repointing.js +0 -0
  119. package/dist/runtime/reversibility.d.ts +11 -9
  120. package/dist/runtime/stakes.d.ts +129 -1
  121. package/dist/runtime/stakes.js +240 -26
  122. package/dist/runtime/vocabulary.d.ts +164 -7
  123. package/dist/runtime/vocabulary.js +181 -8
  124. package/dist/sdk/audit.d.ts +174 -3
  125. package/dist/sdk/audit.js +176 -17
  126. package/dist/sdk/catalogue.d.ts +9 -1
  127. package/dist/sdk/conformance.d.ts +37 -3
  128. package/dist/sdk/conformance.js +25 -4
  129. package/dist/sdk/definition.d.ts +129 -5
  130. package/dist/sdk/definition.js +66 -0
  131. package/dist/sdk/registry.d.ts +45 -2
  132. package/dist/sdk/registry.js +102 -1
  133. package/dist/signals/acted.contract.d.ts +21 -0
  134. package/dist/signals/acted.contract.js +236 -0
  135. package/dist/signals/acted.d.ts +359 -0
  136. package/dist/signals/acted.js +135 -0
  137. package/dist/signals/action-change.d.ts +507 -0
  138. package/dist/signals/action-change.js +265 -0
  139. package/dist/signals/action.d.ts +331 -0
  140. package/dist/signals/action.js +182 -0
  141. package/dist/signals/agenda.d.ts +585 -0
  142. package/dist/signals/agenda.js +295 -0
  143. package/dist/signals/applied-window.contract.d.ts +23 -0
  144. package/dist/signals/applied-window.contract.js +160 -0
  145. package/dist/signals/arrivals.contract.d.ts +21 -0
  146. package/dist/signals/arrivals.contract.js +180 -0
  147. package/dist/signals/arrivals.d.ts +375 -0
  148. package/dist/signals/arrivals.js +254 -0
  149. package/dist/signals/arriving.d.ts +210 -0
  150. package/dist/signals/arriving.js +133 -0
  151. package/dist/signals/audiences.d.ts +528 -0
  152. package/dist/signals/audiences.js +255 -0
  153. package/dist/signals/broadcast.d.ts +33 -17
  154. package/dist/signals/broadcast.js +255 -32
  155. package/dist/signals/change.d.ts +378 -0
  156. package/dist/signals/change.js +327 -0
  157. package/dist/signals/collect.d.ts +169 -34
  158. package/dist/signals/collect.js +186 -38
  159. package/dist/signals/conversion.d.ts +348 -0
  160. package/dist/signals/conversion.js +235 -0
  161. package/dist/signals/copy-change.d.ts +553 -0
  162. package/dist/signals/copy-change.js +377 -0
  163. package/dist/signals/copy.d.ts +337 -0
  164. package/dist/signals/copy.js +211 -0
  165. package/dist/signals/correlated.contract.d.ts +24 -0
  166. package/dist/signals/correlated.contract.js +94 -0
  167. package/dist/signals/counters.d.ts +97 -0
  168. package/dist/signals/counters.js +160 -0
  169. package/dist/signals/deliver.d.ts +23 -4
  170. package/dist/signals/deliver.js +34 -6
  171. package/dist/signals/deployment-change.d.ts +395 -0
  172. package/dist/signals/deployment-change.js +309 -0
  173. package/dist/signals/deployment.d.ts +278 -0
  174. package/dist/signals/deployment.js +178 -0
  175. package/dist/signals/door.d.ts +114 -0
  176. package/dist/signals/door.js +77 -0
  177. package/dist/signals/expire.d.ts +192 -0
  178. package/dist/signals/expire.js +213 -0
  179. package/dist/signals/fold.d.ts +10 -0
  180. package/dist/signals/fold.js +5 -1
  181. package/dist/signals/form-action.d.ts +302 -0
  182. package/dist/signals/form-action.js +169 -0
  183. package/dist/signals/form-copy.d.ts +523 -0
  184. package/dist/signals/form-copy.js +346 -0
  185. package/dist/signals/forms.d.ts +247 -0
  186. package/dist/signals/forms.js +147 -0
  187. package/dist/signals/frontier.d.ts +268 -0
  188. package/dist/signals/frontier.js +145 -0
  189. package/dist/signals/funnel-change.d.ts +548 -0
  190. package/dist/signals/funnel-change.js +361 -0
  191. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  192. package/dist/signals/funnel-hours.contract.js +221 -0
  193. package/dist/signals/funnel-hours.d.ts +293 -0
  194. package/dist/signals/funnel-hours.js +99 -0
  195. package/dist/signals/funnel.d.ts +592 -0
  196. package/dist/signals/funnel.js +231 -0
  197. package/dist/signals/health.d.ts +694 -0
  198. package/dist/signals/health.js +573 -0
  199. package/dist/signals/index.d.ts +60 -0
  200. package/dist/signals/index.js +60 -0
  201. package/dist/signals/ingest.d.ts +56 -1
  202. package/dist/signals/ingest.js +91 -1
  203. package/dist/signals/inside.d.ts +190 -0
  204. package/dist/signals/inside.js +263 -0
  205. package/dist/signals/join.d.ts +56 -0
  206. package/dist/signals/join.js +60 -0
  207. package/dist/signals/journal.d.ts +123 -9
  208. package/dist/signals/kept.contract.d.ts +22 -0
  209. package/dist/signals/kept.contract.js +111 -0
  210. package/dist/signals/kinds.d.ts +8 -6
  211. package/dist/signals/kinds.js +14 -6
  212. package/dist/signals/library-action.d.ts +430 -0
  213. package/dist/signals/library-action.js +336 -0
  214. package/dist/signals/library-agenda-change.d.ts +324 -0
  215. package/dist/signals/library-agenda-change.js +199 -0
  216. package/dist/signals/library-agenda.d.ts +258 -0
  217. package/dist/signals/library-agenda.js +167 -0
  218. package/dist/signals/library-change.d.ts +477 -0
  219. package/dist/signals/library-change.js +335 -0
  220. package/dist/signals/library-copy-change.d.ts +498 -0
  221. package/dist/signals/library-copy-change.js +476 -0
  222. package/dist/signals/library-pace.d.ts +319 -0
  223. package/dist/signals/library-pace.js +305 -0
  224. package/dist/signals/library-reach-change.d.ts +646 -0
  225. package/dist/signals/library-reach-change.js +542 -0
  226. package/dist/signals/library-reach.d.ts +377 -0
  227. package/dist/signals/library-reach.js +227 -0
  228. package/dist/signals/library-senders-change.d.ts +457 -0
  229. package/dist/signals/library-senders-change.js +367 -0
  230. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  231. package/dist/signals/library-senders-reach-change.js +538 -0
  232. package/dist/signals/library-senders-reach.d.ts +340 -0
  233. package/dist/signals/library-senders-reach.js +252 -0
  234. package/dist/signals/library-senders.d.ts +271 -0
  235. package/dist/signals/library-senders.js +180 -0
  236. package/dist/signals/library-word-reach-change.d.ts +567 -0
  237. package/dist/signals/library-word-reach-change.js +564 -0
  238. package/dist/signals/library.d.ts +306 -0
  239. package/dist/signals/library.js +178 -0
  240. package/dist/signals/memory.d.ts +9 -0
  241. package/dist/signals/memory.js +246 -14
  242. package/dist/signals/migrate.d.ts +20 -4
  243. package/dist/signals/migrate.js +269 -8
  244. package/dist/signals/notice.d.ts +389 -0
  245. package/dist/signals/notice.js +250 -0
  246. package/dist/signals/pace-change.d.ts +501 -0
  247. package/dist/signals/pace-change.js +310 -0
  248. package/dist/signals/pace.d.ts +296 -0
  249. package/dist/signals/pace.js +291 -0
  250. package/dist/signals/page-views.d.ts +365 -0
  251. package/dist/signals/page-views.js +218 -0
  252. package/dist/signals/part-pace.d.ts +378 -0
  253. package/dist/signals/part-pace.js +333 -0
  254. package/dist/signals/parts.d.ts +354 -0
  255. package/dist/signals/parts.js +232 -0
  256. package/dist/signals/postgres.d.ts +16 -2
  257. package/dist/signals/postgres.js +753 -76
  258. package/dist/signals/progress.d.ts +212 -0
  259. package/dist/signals/progress.js +150 -0
  260. package/dist/signals/ratios.d.ts +108 -0
  261. package/dist/signals/ratios.js +40 -0
  262. package/dist/signals/reach.d.ts +309 -0
  263. package/dist/signals/reach.js +93 -0
  264. package/dist/signals/readable.d.ts +34 -0
  265. package/dist/signals/readable.js +34 -0
  266. package/dist/signals/readership.d.ts +381 -0
  267. package/dist/signals/readership.js +308 -0
  268. package/dist/signals/region-pages.d.ts +173 -0
  269. package/dist/signals/region-pages.js +62 -0
  270. package/dist/signals/region.d.ts +287 -0
  271. package/dist/signals/region.js +198 -0
  272. package/dist/signals/retention.d.ts +163 -0
  273. package/dist/signals/retention.js +75 -0
  274. package/dist/signals/rhythm.d.ts +302 -0
  275. package/dist/signals/rhythm.js +262 -0
  276. package/dist/signals/rollup.d.ts +194 -4
  277. package/dist/signals/rollup.js +0 -0
  278. package/dist/signals/schema.d.ts +1069 -1
  279. package/dist/signals/schema.js +393 -3
  280. package/dist/signals/signal.d.ts +237 -11
  281. package/dist/signals/signal.js +70 -10
  282. package/dist/signals/silence-census.d.ts +205 -0
  283. package/dist/signals/silence-census.js +87 -0
  284. package/dist/signals/silences.d.ts +1147 -0
  285. package/dist/signals/silences.js +996 -0
  286. package/dist/signals/subtrees.d.ts +123 -0
  287. package/dist/signals/subtrees.js +102 -0
  288. package/dist/signals/tally.d.ts +262 -12
  289. package/dist/signals/unread.d.ts +292 -0
  290. package/dist/signals/unread.js +137 -0
  291. package/dist/signals/window-agenda.d.ts +276 -0
  292. package/dist/signals/window-agenda.js +83 -0
  293. package/dist/signals/window-figures.d.ts +148 -0
  294. package/dist/signals/window-figures.js +42 -0
  295. package/dist/signals/window-funnels.d.ts +88 -0
  296. package/dist/signals/window-funnels.js +47 -0
  297. package/dist/signals/window.d.ts +866 -0
  298. package/dist/signals/window.js +693 -0
  299. package/dist/signals/words.d.ts +24 -0
  300. package/dist/signals/words.js +24 -0
  301. package/dist/store/cache.d.ts +101 -0
  302. package/dist/store/cache.js +149 -0
  303. package/dist/store/history.d.ts +82 -0
  304. package/dist/store/history.js +36 -0
  305. package/dist/store/index.d.ts +30 -0
  306. package/dist/store/index.js +30 -0
  307. package/dist/store/memory.d.ts +2 -1
  308. package/dist/store/memory.js +48 -12
  309. package/dist/store/migrate.d.ts +106 -0
  310. package/dist/store/migrate.js +323 -7
  311. package/dist/store/postgres-applications.d.ts +4 -0
  312. package/dist/store/postgres-applications.js +197 -0
  313. package/dist/store/postgres-audience.d.ts +14 -0
  314. package/dist/store/postgres-audience.js +272 -0
  315. package/dist/store/postgres-holds.d.ts +10 -1
  316. package/dist/store/postgres-holds.js +116 -101
  317. package/dist/store/postgres-policy-log.d.ts +14 -0
  318. package/dist/store/postgres-policy-log.js +240 -0
  319. package/dist/store/postgres-projects.d.ts +4 -0
  320. package/dist/store/postgres-projects.js +217 -0
  321. package/dist/store/postgres.d.ts +17 -1
  322. package/dist/store/postgres.js +60 -9
  323. package/dist/store/replay.d.ts +102 -1
  324. package/dist/store/replay.js +190 -19
  325. package/dist/store/reseed.d.ts +238 -0
  326. package/dist/store/reseed.js +308 -0
  327. package/dist/store/schema.d.ts +762 -2
  328. package/dist/store/schema.js +218 -5
  329. package/dist/store/source.d.ts +57 -1
  330. package/dist/store/source.js +65 -1
  331. package/dist/store/store.d.ts +29 -6
  332. package/dist/submit/resolve.d.ts +1 -1
  333. package/dist/submit/resolve.js +2 -1
  334. package/dist/telemetry/calibration.d.ts +25 -0
  335. package/dist/telemetry/calibration.js +27 -1
  336. package/dist/telemetry/event.d.ts +391 -33
  337. package/dist/telemetry/event.js +84 -20
  338. package/dist/telemetry/index.d.ts +2 -0
  339. package/dist/telemetry/index.js +2 -0
  340. package/dist/telemetry/journal.d.ts +104 -3
  341. package/dist/telemetry/journal.js +9 -0
  342. package/dist/telemetry/lookup.d.ts +27 -0
  343. package/dist/telemetry/lookup.js +18 -0
  344. package/dist/telemetry/memory.js +33 -1
  345. package/dist/telemetry/migrate.js +22 -1
  346. package/dist/telemetry/postgres.d.ts +10 -1
  347. package/dist/telemetry/postgres.js +188 -90
  348. package/dist/telemetry/remeasure.d.ts +78 -0
  349. package/dist/telemetry/remeasure.js +83 -0
  350. package/dist/telemetry/retention.d.ts +2 -2
  351. package/dist/telemetry/schema.d.ts +17 -0
  352. package/dist/telemetry/schema.js +27 -1
  353. package/dist/telemetry/sink.d.ts +2 -2
  354. package/dist/telemetry/window.d.ts +135 -0
  355. package/dist/telemetry/window.js +101 -0
  356. package/dist/testing/application-contract.d.ts +14 -0
  357. package/dist/testing/application-contract.js +270 -0
  358. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  359. package/dist/testing/audience-overlay-contract.js +354 -0
  360. package/dist/testing/contracts.d.ts +13 -7
  361. package/dist/testing/contracts.js +13 -7
  362. package/dist/testing/definitions.d.ts +78 -0
  363. package/dist/testing/definitions.js +134 -9
  364. package/dist/testing/doubles.d.ts +103 -0
  365. package/dist/testing/doubles.js +143 -0
  366. package/dist/testing/index.d.ts +2 -2
  367. package/dist/testing/index.js +2 -2
  368. package/dist/testing/journal-contract.js +297 -6
  369. package/dist/testing/model-contract.d.ts +110 -0
  370. package/dist/testing/model-contract.js +150 -0
  371. package/dist/testing/policy-log-contract.d.ts +26 -0
  372. package/dist/testing/policy-log-contract.js +344 -0
  373. package/dist/testing/project-contract.d.ts +14 -0
  374. package/dist/testing/project-contract.js +266 -0
  375. package/dist/testing/reader-signal-contract.d.ts +27 -2
  376. package/dist/testing/reader-signal-contract.js +475 -5
  377. package/dist/testing/store-contract.d.ts +7 -1
  378. package/dist/testing/store-contract.js +84 -3
  379. package/dist/theme/apply.d.ts +20 -1
  380. package/dist/theme/apply.js +5 -3
  381. package/dist/theme/contrast.d.ts +19 -14
  382. package/dist/theme/contrast.js +181 -17
  383. package/dist/theme/derive.d.ts +22 -0
  384. package/dist/theme/derive.js +54 -1
  385. package/dist/theme/library.js +1 -1
  386. package/dist/theme/measure.d.ts +34 -0
  387. package/dist/theme/measure.js +30 -1
  388. package/dist/theme/palettes.js +7 -7
  389. package/dist/theme/ramp.d.ts +64 -0
  390. package/dist/theme/ramp.js +114 -0
  391. package/dist/theme/registry.d.ts +9 -0
  392. package/dist/theme/registry.js +11 -1
  393. package/dist/theme/separation.d.ts +97 -3
  394. package/dist/theme/separation.js +75 -0
  395. package/dist/tree/apply.js +13 -0
  396. package/dist/tree/compare.d.ts +9 -0
  397. package/dist/tree/compare.js +18 -0
  398. package/dist/tree/mutation.d.ts +18 -0
  399. package/dist/tree/mutation.js +24 -12
  400. package/dist/tree/navigation.d.ts +5 -0
  401. package/dist/tree/navigation.js +32 -10
  402. package/dist/tree/outline.d.ts +7 -0
  403. package/dist/tree/outline.js +9 -5
  404. package/dist/write/computed.d.ts +60 -0
  405. package/dist/write/computed.js +61 -0
  406. package/dist/write/held.d.ts +59 -0
  407. package/dist/write/index.d.ts +5 -2
  408. package/dist/write/index.js +5 -2
  409. package/dist/write/reseed.d.ts +151 -0
  410. package/dist/write/reseed.js +184 -0
  411. package/dist/write/revert.js +2 -16
  412. package/package.json +25 -3
  413. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  414. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,263 @@
1
+ import { outlineTree } from "../tree/outline.js";
2
+ import { actedCountOf, } from "./acted.js";
3
+ import { audiencesIn } from "./audiences.js";
4
+ import { ownCopy, rolesByType } from "./join.js";
5
+ /**
6
+ * **What readers did inside each part of a page, over a range.**
7
+ *
8
+ * [`parts.ts`](parts.ts) joins a window's tallies to the tree they were filed
9
+ * against, which answers *which parts of this page are read and which are
10
+ * scrolled past* — for a window, since counting began, with no clock in it.
11
+ * [`acted.ts`](acted.ts) put a clock on the three kinds a reader aimed at
12
+ * something to cause (0362), which answers *what readers did to this part, by
13
+ * the hour* — for one part, or for a page with the part dimension collapsed.
14
+ *
15
+ * Neither answers the question a page's own shape asks: **a reader pressed
16
+ * something; what was it inside?**
17
+ *
18
+ * ## The payload already refused to answer this, and was right to
19
+ * [0167](../../decisions/0167-a-delegated-signal-names-the-regions-it-happened-inside.md)
20
+ * put `within` on the three delegated kinds — the addressed ancestors a press
21
+ * happened inside — and refused it on `viewed` and `dwelled`, where the payload
22
+ * would have been multiplied by the depth of the page to buy what a server can
23
+ * derive. The fold spends that `within` on one counter: `engaged`, a *distinct
24
+ * count of page views* on each ancestor (`rollup.ts`). Distinct counts do not
25
+ * add and the tally keeps no time, so `engaged` cannot answer *how many presses
26
+ * landed in the pricing band last Tuesday* — and the hourly counter cannot
27
+ * either, because it writes a row for the node a signal **named** and for no
28
+ * ancestor of it.
29
+ *
30
+ * **So the ancestry is derived here, from the tree, and not read off the wire at
31
+ * all.** Every row names a tree, a revision and a node; the tree the counters
32
+ * name says what that node sits inside; a sum over a subtree is the answer. No
33
+ * byte is added to any payload, no browser changes, nothing new is stored, and
34
+ * the reading works on batches whose `within` was missing altogether — which is
35
+ * every batch synthesised on a server or replayed from a fixture (`rollup.ts`
36
+ * names that case).
37
+ *
38
+ * ## Why the sum is exact, which is the whole reason this is publishable
39
+ *
40
+ * Every signal of these three kinds wrote **one** hourly row, on **one** node:
41
+ * the one it named. So a subtree's total counts each action exactly once, at
42
+ * whatever depth it happened, and a part's own count plus the totals of the
43
+ * parts immediately inside it is its own total — an invariant, asserted rather
44
+ * than hoped for. Adding occurrences is safe where adding `views`, `reached` or
45
+ * `engaged` is not (0147, 0284), and `ActedCounts` is separated from its key in
46
+ * `acted.ts` to say so in the types.
47
+ *
48
+ * It is the one counter in this subsystem that a nesting sum may be taken over.
49
+ * A reading that added `engaged` up a tree would count one reader's one press
50
+ * once per ancestor and the row would look right, which is why the shape here
51
+ * is four occurrence counters and nothing else.
52
+ *
53
+ * ## One revision, because the counts are laid on a tree
54
+ *
55
+ * `readReaderActed` reads every revision by default and adds them, which is
56
+ * what a goal wants (0350): a goal is a kind on a part and a part outlives a
57
+ * change to the page around it. This reading cannot do that. It lays counts on
58
+ * **a** tree, and a node's ancestry is a fact about one revision — the band a
59
+ * button sat in last week may not be the band it sits in now, and summing both
60
+ * revisions into one shape would attribute the earlier presses to the later
61
+ * page. Rows of another revision are dropped and counted, as `parts.ts` drops
62
+ * them, so a caller who passed the wrong pair can tell.
63
+ *
64
+ * Audiences, by contrast, **add**. Two forms of a page are two sets of rows over
65
+ * one tree at one revision (0263, 0284), and a press in one form plus a press in
66
+ * the other is two presses — a true count, because these are occurrences and not
67
+ * readers. `parts.ts` refuses a window of two audiences because its figures
68
+ * divide by distinct page views; nothing here divides by anything, so the rows
69
+ * are summed and the audiences they came from are published beside the answer
70
+ * (0297).
71
+ *
72
+ * ## Read time, not rollup time
73
+ *
74
+ * For `parts.ts`' reason, and one more. A declaration is a fact about the
75
+ * library rather than about a window of reading, so baking the join into stored
76
+ * rows makes today's silence permanent. Here the baking would be worse than
77
+ * permanent: it would be a second write per ancestor per hour, which is the
78
+ * payload explosion 0167 refused, moved from the wire into the database.
79
+ *
80
+ * Pure. Handed a tree, one read of the counter and the declarations; reaches no
81
+ * store, no clock and no DOM, and adds nothing to the broadcaster's import
82
+ * graph.
83
+ */
84
+ const NO_COUNTS = Object.freeze({
85
+ activations: 0,
86
+ opens: 0,
87
+ closes: 0,
88
+ completions: 0,
89
+ });
90
+ const counting = () => ({ activations: 0, opens: 0, closes: 0, completions: 0 });
91
+ const addInto = (into, counts) => {
92
+ into.activations += counts.activations;
93
+ into.opens += counts.opens;
94
+ into.closes += counts.closes;
95
+ into.completions += counts.completions;
96
+ };
97
+ const frozen = (counts) => ({
98
+ activations: counts.activations,
99
+ opens: counts.opens,
100
+ closes: counts.closes,
101
+ completions: counts.completions,
102
+ });
103
+ /**
104
+ * Join a range of the hourly counter to the tree and registry it was filed
105
+ * against, and read it as the page's own shape.
106
+ *
107
+ * **One read in, one reading out, and that is a guard rather than an
108
+ * ergonomic.** `parts.ts` can refuse a tally handed in twice because a tally is
109
+ * one row per part; an hour's counter legitimately has many rows per part, so a
110
+ * duplicate here is invisible and would inflate every ancestor of it. Taking a
111
+ * single {@link StoredActed} is what makes *a caller passed the same rows
112
+ * twice* unspellable instead of undetectable (0158).
113
+ *
114
+ * Linear in the parts and in the rows: the rows are bucketed once, the parts are
115
+ * walked once to find each one's nearest addressed ancestor, and the subtree
116
+ * totals are accumulated in one pass back up the same list. The reading the
117
+ * ledger's bound exists for (rule 4) is not allowed to walk a part's ancestors
118
+ * per part.
119
+ */
120
+ export const insideReadingOf = (tree, stored, declarations, range) => {
121
+ const own = new Map();
122
+ const here = [];
123
+ let foreign = 0;
124
+ let outside = 0;
125
+ for (const row of stored.hours) {
126
+ if (row.treeId !== tree.treeId || row.revision !== tree.revision) {
127
+ foreign += 1;
128
+ continue;
129
+ }
130
+ if (row.hour < range.from || row.hour >= range.to) {
131
+ outside += 1;
132
+ continue;
133
+ }
134
+ here.push(row);
135
+ const into = own.get(row.nodeId) ?? counting();
136
+ addInto(into, row);
137
+ own.set(row.nodeId, into);
138
+ }
139
+ const roles = rolesByType(declarations);
140
+ /**
141
+ * The nearest addressed ancestor of each part, found by carrying the stack of
142
+ * open elements down the pre-order walk. A part's own ancestors are therefore
143
+ * never re-walked: the entry whose depth is not below the top of the stack has
144
+ * closed it, which is the only comparison this needs.
145
+ */
146
+ const open = [];
147
+ const addressed = [];
148
+ for (const entry of outlineTree(tree.root)) {
149
+ while (open.length > 0 && (open.at(-1)?.depth ?? 0) >= entry.depth)
150
+ open.pop();
151
+ if (entry.node.kind !== "element")
152
+ continue;
153
+ addressed.push({
154
+ node: entry.node,
155
+ depth: entry.depth,
156
+ withinId: open.at(-1)?.nodeId ?? null,
157
+ });
158
+ open.push({ nodeId: entry.node.id, depth: entry.depth });
159
+ }
160
+ const inside = new Map(addressed.map(({ node }) => [node.id, counting()]));
161
+ const held = new Map(addressed.map(({ node }) => [node.id, 1]));
162
+ /**
163
+ * Reverse pre-order, so every part inside a part has already been totalled
164
+ * when the part itself is reached. One pass, whatever the shape of the page.
165
+ */
166
+ for (const { node, withinId } of [...addressed].reverse()) {
167
+ const subtotal = inside.get(node.id);
168
+ if (subtotal === undefined)
169
+ continue;
170
+ addInto(subtotal, own.get(node.id) ?? NO_COUNTS);
171
+ if (withinId === null)
172
+ continue;
173
+ const above = inside.get(withinId);
174
+ if (above !== undefined)
175
+ addInto(above, subtotal);
176
+ const count = held.get(withinId);
177
+ if (count !== undefined)
178
+ held.set(withinId, count + (held.get(node.id) ?? 1));
179
+ }
180
+ const parts = addressed.map(({ node, depth, withinId }) => {
181
+ const subtotal = inside.get(node.id);
182
+ return {
183
+ nodeId: node.id,
184
+ type: node.type,
185
+ role: roles.get(node.type) ?? null,
186
+ depth,
187
+ withinId,
188
+ own: frozen(own.get(node.id) ?? counting()),
189
+ inside: subtotal === undefined ? NO_COUNTS : frozen(subtotal),
190
+ parts: held.get(node.id) ?? 1,
191
+ copy: ownCopy(node, declarations),
192
+ };
193
+ });
194
+ const total = counting();
195
+ for (const part of parts)
196
+ addInto(total, part.own);
197
+ const names = new Set(parts.map((part) => part.nodeId));
198
+ return {
199
+ treeId: tree.treeId,
200
+ revision: tree.revision,
201
+ range,
202
+ parts,
203
+ total: frozen(total),
204
+ audiences: audiencesIn(here),
205
+ counted: here.length,
206
+ foreign,
207
+ outside,
208
+ orphaned: [...own.keys()].filter((nodeId) => !names.has(nodeId)),
209
+ ...(stored.begins === undefined ? {} : { begins: stored.begins }),
210
+ };
211
+ };
212
+ /**
213
+ * The parts readers acted on most in the range, most first.
214
+ *
215
+ * **By what readers did to the part itself**, never by what they did inside it:
216
+ * ordering by `inside` ranks every page by its outermost part, because an
217
+ * ancestor's total is never below its descendant's. The question this answers is
218
+ * *what did readers press*, and the answer to that is a button.
219
+ *
220
+ * One kind, for `actedSeriesOf`' reason — a list with presses and sends added
221
+ * together is a list of two different things — and parts nobody did anything to
222
+ * are absent rather than listed as noughts: the universe of parts that *could*
223
+ * have been pressed is not something a tree can say today, so a list padded with
224
+ * every heading on the page would read as a claim this reading cannot make.
225
+ * {@link InsideReading.parts} holds the whole page for a caller that wants it.
226
+ *
227
+ * Ties keep reading order, so a page with ten parts at one press each is drawn
228
+ * in the order it is written rather than in the order a sort happened to leave
229
+ * them.
230
+ */
231
+ export const actedMostIn = (reading, kind, limit) => {
232
+ const ordered = reading.parts
233
+ .filter((part) => actedCountOf(part.own, kind) > 0)
234
+ .sort((left, right) => actedCountOf(right.own, kind) - actedCountOf(left.own, kind));
235
+ return limit === undefined ? ordered : ordered.slice(0, limit);
236
+ };
237
+ /**
238
+ * The share of everything readers did on the page, in one kind, that happened
239
+ * inside one part — between 0 and 1.
240
+ *
241
+ * *Sixty-two per cent of the presses on this page were in the pricing band* is
242
+ * the sentence, and it is exact rather than estimated: the numerator and the
243
+ * denominator are counts of the same occurrences over the same rows, and each
244
+ * occurrence is in both or in neither.
245
+ *
246
+ * `null` where readers did nothing of that kind on the page at all. A nought
247
+ * there would read as *this part gets none of them*, which is a claim about the
248
+ * part, and what is true is that there are none to share out.
249
+ */
250
+ export const insideShareIn = (reading, part, kind) => {
251
+ const whole = actedCountOf(reading.total, kind);
252
+ return whole === 0 ? null : actedCountOf(part.inside, kind) / whole;
253
+ };
254
+ /**
255
+ * What readers did inside a part but not to the part itself.
256
+ *
257
+ * The figure that says whether a band is a thing readers use or a thing that
258
+ * holds things readers use — and the one a surface would otherwise get by
259
+ * subtracting two numbers it was handed, which is the subtraction that is wrong
260
+ * if either of them is the other kind's.
261
+ */
262
+ export const beneathOf = (part, kind) => actedCountOf(part.inside, kind) - actedCountOf(part.own, kind);
263
+ //# sourceMappingURL=inside.js.map
@@ -0,0 +1,56 @@
1
+ import type { PrimitiveType } from "../primitive-type.js";
2
+ import { type PrimitiveRole } from "../role.js";
3
+ import { type CopyDeclarations, type NodeCopy } from "../sdk/copy.js";
4
+ import type { ElementNode } from "../tree/node.js";
5
+ /**
6
+ * The two rules both joins of a window to a tree have to get the same answer
7
+ * to, spelled once.
8
+ *
9
+ * [`parts.ts`](parts.ts) joins the tallies and [`inside.ts`](inside.ts) joins
10
+ * the hourly counter, and both have to say what part a primitive plays (0114)
11
+ * and what words a part says itself (0122). Two spellings of either would be
12
+ * two chances for one of them to be wrong, and the second rule carries a
13
+ * sentence that a caller relies on: *the words of a page are partitioned across
14
+ * its parts exactly once*, which is what lets two rows be added together
15
+ * without a headline being read twice.
16
+ *
17
+ * **Not a published door.** These are the private middle of two readings rather
18
+ * than anything a host asks for, and `@jam-overture/loom/signals` is wide
19
+ * enough already — so this module is deliberately absent from the barrel, as
20
+ * `counters.ts` and `words.ts` are.
21
+ */
22
+ /**
23
+ * Which types declared each role, as a registry answers it.
24
+ *
25
+ * The same shape as `CopyDeclarations` and for the same reason (0122): a
26
+ * registry built by the SDK satisfies it, and so does a two-line double in a
27
+ * test. The inverse — a type's role — is what both joins need and is not what
28
+ * 0114 exposes, because a role is a question asked of the vocabulary rather than
29
+ * of a component. The vocabulary is closed and exported, so the inversion is a
30
+ * walk of `PRIMITIVE_ROLES` rather than a method on the registry.
31
+ *
32
+ * Published, by way of `parts.ts` — a deployment hands one of these in.
33
+ */
34
+ export type RoleDeclarations = {
35
+ readonly typesWithRole: (role: PrimitiveRole) => readonly PrimitiveType[];
36
+ };
37
+ /**
38
+ * A type's role, inverted from the vocabulary once per reading.
39
+ *
40
+ * Linear in the vocabulary rather than per part: the alternative is asking
41
+ * `typesWithRole` for every part, which is a registry call and a list scan per
42
+ * node on a page that may have thousands.
43
+ */
44
+ export declare const rolesByType: (declarations: RoleDeclarations) => ReadonlyMap<PrimitiveType, PrimitiveRole>;
45
+ /**
46
+ * What a part says on its own, read with `copyIn` against a node stripped of
47
+ * everything that is a part in its own right.
48
+ *
49
+ * `copyIn` walks a subtree, which is right for its callers and wrong here — a
50
+ * root would carry every word on the page and so would every band on the way
51
+ * down. Rather than reimplement its rules about blank strings, non-string values
52
+ * and what counts as declared, this hands it the node with only the children
53
+ * that are nobody else's, which is exactly the part's own contribution.
54
+ */
55
+ export declare const ownCopy: (node: ElementNode, declarations: CopyDeclarations) => NodeCopy;
56
+ //# sourceMappingURL=join.d.ts.map
@@ -0,0 +1,60 @@
1
+ import { PRIMITIVE_ROLES } from "../role.js";
2
+ import { copyIn } from "../sdk/copy.js";
3
+ /**
4
+ * A type's role, inverted from the vocabulary once per reading.
5
+ *
6
+ * Linear in the vocabulary rather than per part: the alternative is asking
7
+ * `typesWithRole` for every part, which is a registry call and a list scan per
8
+ * node on a page that may have thousands.
9
+ */
10
+ export const rolesByType = (declarations) => {
11
+ const byType = new Map();
12
+ for (const role of PRIMITIVE_ROLES) {
13
+ for (const type of declarations.typesWithRole(role)) {
14
+ /**
15
+ * First declaration wins, and it cannot legitimately happen twice: a
16
+ * definition carries one `role`. A registry that answered the same type
17
+ * for two roles is wrong about something this reading cannot fix, and
18
+ * picking the earlier keeps the answer stable rather than dependent on
19
+ * the vocabulary's order.
20
+ */
21
+ if (!byType.has(type))
22
+ byType.set(type, role);
23
+ }
24
+ }
25
+ return byType;
26
+ };
27
+ /**
28
+ * The children that are not parts in their own right, which is what a node
29
+ * contributes itself.
30
+ *
31
+ * Text is kept and an element is dropped, because every element is a part of
32
+ * this reading and would otherwise be counted at two depths. **A slot is kept
33
+ * and pruned the same way**, because a slot is not an element and so is never a
34
+ * part: text handed into one belongs to the nearest element above it, and a slot
35
+ * treated as an element would lose those words to a node this reading never
36
+ * reports. The words of a page are partitioned across its parts exactly once,
37
+ * and that sentence is only true with this clause in it.
38
+ */
39
+ const ownChildren = (children) => children.flatMap((child) => {
40
+ switch (child.kind) {
41
+ case "element":
42
+ return [];
43
+ case "text":
44
+ return [child];
45
+ case "slot":
46
+ return [{ ...child, children: ownChildren(child.children) }];
47
+ }
48
+ });
49
+ /**
50
+ * What a part says on its own, read with `copyIn` against a node stripped of
51
+ * everything that is a part in its own right.
52
+ *
53
+ * `copyIn` walks a subtree, which is right for its callers and wrong here — a
54
+ * root would carry every word on the page and so would every band on the way
55
+ * down. Rather than reimplement its rules about blank strings, non-string values
56
+ * and what counts as declared, this hands it the node with only the children
57
+ * that are nobody else's, which is exactly the part's own contribution.
58
+ */
59
+ export const ownCopy = (node, declarations) => copyIn({ ...node, children: ownChildren(node.children) }, declarations);
60
+ //# sourceMappingURL=join.js.map
@@ -1,15 +1,32 @@
1
+ import type { AudienceId } from "../audience/audience.js";
1
2
  import type { TreeId } from "../ids.js";
2
3
  import { type PageDirection, type PageEnds } from "../paging.js";
3
4
  import type { Result } from "../result.js";
4
- import type { ReaderSignalBatch } from "./signal.js";
5
+ import type { ReaderSignalBatch, ViewKey } from "./signal.js";
5
6
  /**
6
- * Where batches wait to be rolled up.
7
+ * Where deliveries wait to be rolled up, and then where they are kept.
7
8
  *
8
- * This is a **buffer, not an archive**, and everything about it follows from
9
- * that. Aggregates are the durable artefact (0146); raw batches exist for as
10
- * long as it takes rollup to read them and no longer. A deployment that kept
11
- * them would hold the largest table in its database in order to answer
12
- * questions that are all about counters.
9
+ * It was a **buffer, not an archive**, and until 5 November everything about it
10
+ * followed from that: aggregates are the durable artefact (0146), and a raw
11
+ * batch existed for as long as it took rollup to read it and no longer. That is
12
+ * now two lifetimes rather than one
13
+ * ([0351](../../decisions/0351-a-counted-delivery-is-kept-for-a-stated-window-rather-than-deleted-by-the-fold.md),
14
+ * and the policy it serves,
15
+ * [0349](../../decisions/0349-a-projects-reader-events-are-kept-thirty-days-by-default-and-the-tallies-stay-the-durable-record.md)):
16
+ * a delivery is **counted** when it ripens and **deleted** when it is past the
17
+ * window its deployment keeps events for, thirty days by default.
18
+ *
19
+ * **The aggregates are still the durable record.** Nothing read over all time
20
+ * comes out of this table; what the kept window buys is that an operator can
21
+ * look at individual deliveries for as long as it lasts, which is what
22
+ * `docs/portal.md`'s *Events* tab is. Everything a counter answers, a counter
23
+ * goes on answering after the row is gone.
24
+ *
25
+ * So there are two positions in this table rather than one, and they move
26
+ * independently: {@link ReaderSignalJournal.counted} stamps the fold's
27
+ * instant on a prefix, and {@link ReaderSignalJournal.forget} deletes one.
28
+ * **Nothing may delete a row the fold has not stamped** — that rule lives in
29
+ * `expire.ts`, which is the only caller that deletes.
13
30
  *
14
31
  * It is deliberately the same shape as `src/telemetry/journal.ts` — append,
15
32
  * page by an opaque cursor, forget a prefix — because a second paged log that
@@ -17,7 +34,10 @@ import type { ReaderSignalBatch } from "./signal.js";
17
34
  * cursor rules to be subtly wrong. What it is not is the same *table*: a
18
35
  * journal holds what the runtime said about itself, and this holds what
19
36
  * browsers said about pages, and the two have different retention and different
20
- * volumes by two orders of magnitude.
37
+ * volumes by two orders of magnitude. The fourth operation is where the two
38
+ * shapes part company, and it is the retention rule that asked for it: a
39
+ * telemetry episode is deleted by age alone, and a delivery may not be deleted
40
+ * until it has been counted.
21
41
  */
22
42
  /**
23
43
  * The only way it fails. No `not-found` — reading a tree nothing has been
@@ -40,10 +60,67 @@ export declare const describeReaderSignalStoreError: (error: ReaderSignalStoreEr
40
60
  export type ReceivedBatch = ReaderSignalBatch & {
41
61
  readonly seq: number;
42
62
  readonly receivedAt: string;
63
+ /**
64
+ * The audience it was **filed** under, which is resolved rather than
65
+ * optional (0284).
66
+ *
67
+ * `audience` is what the sender said and may be absent; this is what the
68
+ * buffer stored, and a stored row always names one — `aud_everyone` where the
69
+ * sender named nothing. A fold reads this, so that a window holding two
70
+ * audiences folds into two sets of counters rather than one.
71
+ */
72
+ readonly audienceId: AudienceId;
73
+ /**
74
+ * When a fold counted this delivery into the counters, where one has (0351).
75
+ *
76
+ * Absent is *not yet counted*, which is what every row in the table used to
77
+ * be: before the kept window existed a counted delivery was deleted in the
78
+ * same operation, so there was no state to record. It is the only field on a
79
+ * stored row that changes after it is written, and only one writer sets it.
80
+ *
81
+ * **It is the fold's own instant, not the row's age.** `receivedAt` is what
82
+ * retention measures and this is what makes a row eligible for it — a
83
+ * delivery is deleted when it is both past the kept window and stamped here,
84
+ * never on one of the two (`expire.ts`).
85
+ */
86
+ readonly foldedAt?: string;
43
87
  };
44
88
  export type ReaderSignalReadRequest = {
45
89
  /** Absent reads every tree the handle can see, which is the scope rule (0020). */
46
90
  readonly treeId?: TreeId;
91
+ /**
92
+ * Narrow to rows the fold has counted, or to rows it has not.
93
+ *
94
+ * Absent reads both, which is what a surface listing deliveries wants and
95
+ * what every caller wanted when a counted row did not outlive its fold.
96
+ *
97
+ * **`false` is the collection scan's read and the reason this exists.** The
98
+ * scan runs from the oldest end looking for the oldest ripe delivery, and the
99
+ * oldest end of a table that keeps deliveries for thirty days is thirty days
100
+ * of rows that have already been counted. Without the filter, collection's
101
+ * cost would grow with the kept window rather than with the window it folds
102
+ * — and the kept window is the one a deployment is invited to lengthen.
103
+ */
104
+ readonly counted?: boolean;
105
+ /**
106
+ * Narrow to the deliveries of **one page view**, named by its key (0355).
107
+ *
108
+ * The one correlation the subsystem allows, and the whole of it: a caller
109
+ * hands in a key it is already holding — off a row it could already see —
110
+ * and gets that page view's deliveries. There is deliberately nothing here
111
+ * that would **enumerate** keys, and nothing that takes a row and asks *what
112
+ * else shares this one's key*, because either of those is a stitching
113
+ * primitive wearing a narrowing's clothes. One key in, one page view out.
114
+ *
115
+ * It is a filter rather than a second method so that the paging rules are the
116
+ * ones this request already has. A page view holds few deliveries, but *few*
117
+ * is a sender's choice rather than a bound, so the read that serves a drawer
118
+ * is a page like every other read here.
119
+ *
120
+ * Served by a partial index on the column, which exists because a delivery
121
+ * that names no page view is never looked up by one.
122
+ */
123
+ readonly view?: ViewKey;
47
124
  /** A cursor from a previous page's `older`/`newer`, passed back unread. */
48
125
  readonly cursor?: string;
49
126
  /** Default `newer`, which with no cursor is the oldest page — where rollup starts. */
@@ -78,7 +155,36 @@ export type ForgetOutcome = {
78
155
  readonly removed: number;
79
156
  };
80
157
  /**
81
- * Three operations, mirroring the journal's.
158
+ * What the fold is asked to stamp, as a position and the instant to write.
159
+ *
160
+ * The same prefix shape {@link ForgetBefore} takes, because it replaces that
161
+ * call in the one place a fold used to make it: counting and dropping were one
162
+ * operation and are now counting and *marking*, which is the same operation
163
+ * against a table that keeps the row (0351).
164
+ *
165
+ * The instant is the fold's, handed in rather than read from a clock here, for
166
+ * the reason every other stored timestamp in this subsystem is handed in: a run
167
+ * writes one instant across every row and every counter it touches, and a store
168
+ * that read its own clock would stamp rows a run did not think it was stamping.
169
+ */
170
+ export type CountedBefore = {
171
+ readonly before: number;
172
+ readonly at: string;
173
+ };
174
+ export type CountedOutcome = {
175
+ /**
176
+ * Rows this call stamped.
177
+ *
178
+ * Only rows that carried nothing: a row already stamped is left exactly as it
179
+ * was, so a second run over the same prefix reports nought rather than moving
180
+ * an instant that a reading has already been taken against. It is what makes
181
+ * this operation safe to repeat, which matters because the run that makes it
182
+ * is the run that has already made the counters durable.
183
+ */
184
+ readonly counted: number;
185
+ };
186
+ /**
187
+ * Four operations: the journal's three, and the stamp the kept window asked for.
82
188
  *
83
189
  * `receive` takes several batches because an ingestion endpoint may be handed
84
190
  * several and should pay for one round trip. Unlike a journal's, this batch has
@@ -89,6 +195,14 @@ export type ForgetOutcome = {
89
195
  export interface ReaderSignalJournal {
90
196
  readonly receive: (batches: readonly ReaderSignalBatch[]) => Promise<Result<void, ReaderSignalStoreError>>;
91
197
  readonly read: (request?: ReaderSignalReadRequest) => Promise<Result<ReaderSignalPage, ReaderSignalStoreError>>;
198
+ /**
199
+ * Record that a fold counted every row below a position (0351).
200
+ *
201
+ * Idempotent by construction — it stamps only what carries nothing — because
202
+ * the caller has already written the counters when it gets here, so the one
203
+ * thing it must never do is make a retry worse than the failure.
204
+ */
205
+ readonly counted: (request: CountedBefore) => Promise<Result<CountedOutcome, ReaderSignalStoreError>>;
92
206
  readonly forget: (request: ForgetBefore) => Promise<Result<ForgetOutcome, ReaderSignalStoreError>>;
93
207
  }
94
208
  //# sourceMappingURL=journal.d.ts.map
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The fifth contract suite both reader-signal journals are run against: **a
3
+ * counted delivery is marked rather than deleted, and the mark is what the next
4
+ * fold reads** (0351).
5
+ *
6
+ * It is here rather than beside the three in `src/testing/reader-signal-contract.ts`
7
+ * for the reason `applied-window.contract.ts` is: that directory is another
8
+ * lane's and this is reader-signal work. The finding filed with 0316 asks for
9
+ * the set to be moved together, which is one import away.
10
+ *
11
+ * **Every property here needs two implementations to be worth asserting**,
12
+ * which is what earns it a contract rather than a test beside the memory store.
13
+ * The stamp has to be idempotent, and in Postgres that is a clause in a `WHERE`
14
+ * — `folded_at IS NULL` — while in memory it is a guard in a `map`. The filter
15
+ * has to tell three states apart, and in Postgres `null` is one of them while
16
+ * in memory the field is absent. Those are exactly the differences that make
17
+ * two stores quietly disagree, and the disagreement here would be a window
18
+ * counted twice (0158).
19
+ */
20
+ import type { ReaderSignalJournal } from "./journal.js";
21
+ export declare const describeKeptDeliveryContract: (name: string, make: () => Promise<ReaderSignalJournal> | ReaderSignalJournal) => void;
22
+ //# sourceMappingURL=kept.contract.d.ts.map