@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,187 @@
1
+ /**
2
+ * The live pages a customer's server holds, and the one question a render asks
3
+ * of them.
4
+ *
5
+ * Loom is not in the render path (0262), so a page that an accepted change has
6
+ * moved cannot be fetched while a reader waits for it. What the server does
7
+ * instead is keep the project's live pages in its own process and draw from
8
+ * what it holds — and this is that holding, as a value rather than as a mutable
9
+ * cache. Every pull produces a new one; nothing here is edited in place, so a
10
+ * render that has already read a page cannot have it changed underneath.
11
+ *
12
+ * **A page this does not hold is not an error.** `livePageOf` answers
13
+ * `undefined`, and the caller renders the page as it was built. That is the
14
+ * whole of the fallback a host has to write, and it is the same answer for a
15
+ * server that has never pulled, a pull that failed, and a page the answer did
16
+ * not name.
17
+ */
18
+ import type { AudienceId } from "../audience/audience.js";
19
+ import { type AudienceForm, type ComposeError } from "../audience/compose.js";
20
+ import { type AudienceRule } from "../audience/rule.js";
21
+ import type { TreeId } from "../ids.js";
22
+ import type { JsonObject } from "../json.js";
23
+ import type { LoomTree } from "../tree/tree.js";
24
+ import { type LiveWindow } from "./window.js";
25
+ /**
26
+ * What a pull leaves behind: the pages, the rules that sort their readers, the
27
+ * tag that names both, and enough of the last outcome to say whether the site
28
+ * is current.
29
+ *
30
+ * The tag, the pages and the rules travel together by construction. A pull that
31
+ * cannot be read moves none of them, so the tag always names what is held beside
32
+ * it — which is what makes it safe to send back as `If-None-Match` — and a site
33
+ * never sorts readers by one pull's rules on another pull's pages (0371 clause
34
+ * 4).
35
+ */
36
+ export type LivePages = {
37
+ /** The live pages, by the id of the page each one is. */
38
+ readonly pages: ReadonlyMap<TreeId, LoomTree>;
39
+ /**
40
+ * Each live page's segment rules, in the order the portal set. A page with
41
+ * none is absent, and every reader of it is in no segment (0371).
42
+ */
43
+ readonly rules: ReadonlyMap<TreeId, readonly AudienceRule[]>;
44
+ /**
45
+ * Each live page's segment forms: the delta one segment's readers are served
46
+ * over the base (0263, 0371). A page with none is absent,
47
+ * and so is a segment that is only a name — which is what every segment was
48
+ * before the door answered forms.
49
+ */
50
+ readonly forms: ReadonlyMap<TreeId, readonly AudienceForm[]>;
51
+ /**
52
+ * How long this project holds its readers, and each page's versions a pin can
53
+ * still be served (0383). `WINDOW_OFF` where nobody chose a window, and for a
54
+ * door from before the window answered one.
55
+ */
56
+ readonly window: LiveWindow;
57
+ /** The entity tag the door gave for exactly these pages, if it gave one. */
58
+ readonly tag: string | undefined;
59
+ /** When the door last answered, whether it answered pages or `304`. */
60
+ readonly pulledAt: number | undefined;
61
+ /** When these pages arrived, which is older than `pulledAt` after a `304`. */
62
+ readonly freshAt: number | undefined;
63
+ /** Failed pulls since the last one the door answered. Zero while current. */
64
+ readonly failures: number;
65
+ };
66
+ /**
67
+ * A server that has not pulled yet, which is every server at the moment it
68
+ * starts.
69
+ *
70
+ * It renders every page as built, so a deployment whose pull is misconfigured
71
+ * serves its site rather than an error — the property the pull exists to keep
72
+ * (0358 clause 4) is true before the first pull as well as after a failed one.
73
+ */
74
+ export declare const NO_LIVE_PAGES: LivePages;
75
+ /**
76
+ * The live page for this page id, or `undefined` to render the page as built.
77
+ *
78
+ * This is the only call a render path makes. Selection for an audience (0263)
79
+ * happens after it, in the customer's process, against the tree this answers —
80
+ * the pull carries no audience and the door refuses a request that names one.
81
+ *
82
+ * **With a reader's pin, the version they were pinned to** (0383 clause 2),
83
+ * which is the newest version of this page live at or before the pin. A pin the
84
+ * server cannot resolve, and a page it holds no earlier version of, read the
85
+ * newest live page; so does every reader of a project with no window, which is
86
+ * every project until one is chosen. `pinIn` reads the pin from the request's
87
+ * `Cookie` header and nothing about the reader goes any further than this call.
88
+ *
89
+ * The pin is an optional argument rather than a second function because the
90
+ * question is one question — *what do I draw for this reader* — and a host that
91
+ * honours a window should not have a second call to remember on each page.
92
+ */
93
+ export declare const livePageOf: (held: LivePages, page: TreeId, pin?: number) => LoomTree | undefined;
94
+ /**
95
+ * The segment this reader of this page is in, or `undefined` for none — which
96
+ * is `aud_everyone`, and is what a page with no rules answers for every reader.
97
+ *
98
+ * **Decided here, in the site's process, and never sent anywhere** (0262,
99
+ * 0371 clause 2). The context is whatever the host's server knows while it
100
+ * draws the page — `device`, `source`, `returning`, the keys its rules were
101
+ * written against — and none of it leaves this function: what comes out is a
102
+ * segment's name, which the host stamps on the page it renders so the page's
103
+ * signals are filed under it (0284).
104
+ *
105
+ * **One segment, the last rule that matches** (0385). A batch names one
106
+ * audience, so a reader two rules match is counted in one segment rather than
107
+ * in both, which would count one page view twice wherever segments are added
108
+ * up. The last rule is the one the portal orders general to specific, and the
109
+ * one that wins a contested part of the page (0359 clause 3), so it is the form
110
+ * the reader will be served once a segment has a form of its own.
111
+ *
112
+ * **This answers the name a signal is filed under, not the page that is
113
+ * served.** Which deltas a reader gets is `pageForReader`, and it is not the
114
+ * same question: a reader two rules match is in one segment for counting and
115
+ * is served both of their forms, in the deployment's order (0359 clause 3).
116
+ */
117
+ export declare const segmentOf: (held: LivePages, page: TreeId, context: JsonObject | undefined) => AudienceId | undefined;
118
+ /**
119
+ * A page as one reader gets it: what to render, and what to call them while
120
+ * they read it.
121
+ */
122
+ export type ServedPage = {
123
+ /** The tree to render — the live page with this reader's forms applied. */
124
+ readonly tree: LoomTree;
125
+ /**
126
+ * The segment to file this page view under (0284), or `undefined` for
127
+ * `aud_everyone`. Absent after a refusal, because the reader got the base.
128
+ */
129
+ readonly audience: AudienceId | undefined;
130
+ /**
131
+ * Why the forms were not applied, for the host's log. `undefined` on every
132
+ * request a deployment intends, including every request of a page with no
133
+ * segments at all.
134
+ */
135
+ readonly refusal: ComposeError | undefined;
136
+ };
137
+ /**
138
+ * What to render for this reader, and what to file their signals under.
139
+ *
140
+ * The one call a render path makes once a deployment has segments: it answers
141
+ * the live page composed with the forms this reader's segments earn, the
142
+ * segment's name for the page's signals, and — where the forms could not be
143
+ * applied — why.
144
+ *
145
+ * **A form that cannot be applied costs the reader their segment, not their
146
+ * page.** The two properties either side of this are both worth keeping and
147
+ * they pull apart exactly here. A pull that fails costs freshness and never the
148
+ * page (0358 clause 4), so there is always something to render. A composition
149
+ * refuses rather than falling back to the base (0263 clause 4), because a
150
+ * reader served the base whose page views are filed under `aud_eu` makes the
151
+ * comparison between two segments a comparison between one segment's form and
152
+ * another segment's *name over the base*.
153
+ *
154
+ * Dropping the audience keeps both: the reader gets the base page, their
155
+ * signals say what they were actually shown, and the deployment's figures stay
156
+ * a comparison of forms readers were served. The refusal is handed back rather
157
+ * than swallowed because a segment whose form has gone stale is a thing
158
+ * somebody must be told about — it is silent otherwise, and silently serving
159
+ * the base is the state 0263 clause 4 refuses.
160
+ *
161
+ * A deployment with no segments, a reader the rules do not match, and a server
162
+ * that has never pulled all answer the same way: the page, and no segment.
163
+ *
164
+ * **The pin is applied first, and the segment is chosen against the version it
165
+ * chose** (0383, *Audiences*). The rules sort the reader as they do now — they
166
+ * read the context, never the page — but the forms were authored against the
167
+ * version in `pages`, so a form that does not apply to the version a pinned
168
+ * reader was given is refused by the composition, and this answers that reader
169
+ * the version they were pinned to without their segment's form. That is the
170
+ * same trade `refusal` already describes one dimension across: the reader keeps
171
+ * their page, their signals say they were shown the base, and the deployment is
172
+ * told why.
173
+ */
174
+ export declare const pageForReader: (held: LivePages, built: LoomTree, context: JsonObject | undefined, pin?: number) => ServedPage;
175
+ /** Every live page held, in the order the door answered them. */
176
+ export declare const livePagesHeld: (held: LivePages) => readonly LoomTree[];
177
+ /**
178
+ * Whether the server is drawing on pages the door confirmed, rather than on
179
+ * nothing.
180
+ *
181
+ * A site holding pages after ten failed pulls is still serving Loom's pages,
182
+ * which is the behaviour clause 4 asks for and not a state worth hiding. What
183
+ * `failures` is for is saying so out loud in a log; what this is for is the
184
+ * simpler question of whether the door has ever been reached.
185
+ */
186
+ export declare const isPulling: (held: LivePages) => boolean;
187
+ //# sourceMappingURL=pages.d.ts.map
@@ -0,0 +1,161 @@
1
+ /**
2
+ * The live pages a customer's server holds, and the one question a render asks
3
+ * of them.
4
+ *
5
+ * Loom is not in the render path (0262), so a page that an accepted change has
6
+ * moved cannot be fetched while a reader waits for it. What the server does
7
+ * instead is keep the project's live pages in its own process and draw from
8
+ * what it holds — and this is that holding, as a value rather than as a mutable
9
+ * cache. Every pull produces a new one; nothing here is edited in place, so a
10
+ * render that has already read a page cannot have it changed underneath.
11
+ *
12
+ * **A page this does not hold is not an error.** `livePageOf` answers
13
+ * `undefined`, and the caller renders the page as it was built. That is the
14
+ * whole of the fallback a host has to write, and it is the same answer for a
15
+ * server that has never pulled, a pull that failed, and a page the answer did
16
+ * not name.
17
+ */
18
+ import { composeTreeForContext, } from "../audience/compose.js";
19
+ import { ruleMatches } from "../audience/rule.js";
20
+ import { heldVersionFor, WINDOW_OFF } from "./window.js";
21
+ /**
22
+ * A server that has not pulled yet, which is every server at the moment it
23
+ * starts.
24
+ *
25
+ * It renders every page as built, so a deployment whose pull is misconfigured
26
+ * serves its site rather than an error — the property the pull exists to keep
27
+ * (0358 clause 4) is true before the first pull as well as after a failed one.
28
+ */
29
+ export const NO_LIVE_PAGES = {
30
+ pages: new Map(),
31
+ rules: new Map(),
32
+ forms: new Map(),
33
+ window: WINDOW_OFF,
34
+ tag: undefined,
35
+ pulledAt: undefined,
36
+ freshAt: undefined,
37
+ failures: 0,
38
+ };
39
+ /**
40
+ * The live page for this page id, or `undefined` to render the page as built.
41
+ *
42
+ * This is the only call a render path makes. Selection for an audience (0263)
43
+ * happens after it, in the customer's process, against the tree this answers —
44
+ * the pull carries no audience and the door refuses a request that names one.
45
+ *
46
+ * **With a reader's pin, the version they were pinned to** (0383 clause 2),
47
+ * which is the newest version of this page live at or before the pin. A pin the
48
+ * server cannot resolve, and a page it holds no earlier version of, read the
49
+ * newest live page; so does every reader of a project with no window, which is
50
+ * every project until one is chosen. `pinIn` reads the pin from the request's
51
+ * `Cookie` header and nothing about the reader goes any further than this call.
52
+ *
53
+ * The pin is an optional argument rather than a second function because the
54
+ * question is one question — *what do I draw for this reader* — and a host that
55
+ * honours a window should not have a second call to remember on each page.
56
+ */
57
+ export const livePageOf = (held, page, pin) => heldVersionFor(held.window, page, pin) ?? held.pages.get(page);
58
+ /**
59
+ * The segment this reader of this page is in, or `undefined` for none — which
60
+ * is `aud_everyone`, and is what a page with no rules answers for every reader.
61
+ *
62
+ * **Decided here, in the site's process, and never sent anywhere** (0262,
63
+ * 0371 clause 2). The context is whatever the host's server knows while it
64
+ * draws the page — `device`, `source`, `returning`, the keys its rules were
65
+ * written against — and none of it leaves this function: what comes out is a
66
+ * segment's name, which the host stamps on the page it renders so the page's
67
+ * signals are filed under it (0284).
68
+ *
69
+ * **One segment, the last rule that matches** (0385). A batch names one
70
+ * audience, so a reader two rules match is counted in one segment rather than
71
+ * in both, which would count one page view twice wherever segments are added
72
+ * up. The last rule is the one the portal orders general to specific, and the
73
+ * one that wins a contested part of the page (0359 clause 3), so it is the form
74
+ * the reader will be served once a segment has a form of its own.
75
+ *
76
+ * **This answers the name a signal is filed under, not the page that is
77
+ * served.** Which deltas a reader gets is `pageForReader`, and it is not the
78
+ * same question: a reader two rules match is in one segment for counting and
79
+ * is served both of their forms, in the deployment's order (0359 clause 3).
80
+ */
81
+ export const segmentOf = (held, page, context) => context === undefined
82
+ ? undefined
83
+ : (held.rules.get(page) ?? []).filter((rule) => ruleMatches(rule, context)).at(-1)?.audienceId;
84
+ /**
85
+ * The page and the rules a request composes from, with the rules narrowed to
86
+ * the segments that have a form.
87
+ *
88
+ * **A rule whose segment has no form is left out rather than refused.** A
89
+ * composition assembled by one writer treats a missing delta as a lost write,
90
+ * which is what `no-form` is for; a live pull assembles its overlay from two
91
+ * lists the door answers independently, and a segment that has rules and no
92
+ * form yet is the ordinary state of every segment made before anybody wrote
93
+ * one for it. Readers are still sorted into it (`segmentOf` reads every rule),
94
+ * and they are served the base — which is what they were served on the day the
95
+ * segment was named, and what pieces 1 to 3 of 0371 shipped.
96
+ */
97
+ const overlayFor = (rules, forms) => ({
98
+ rules: rules.filter((rule) => forms.some((form) => form.audienceId === rule.audienceId)),
99
+ forms,
100
+ });
101
+ /**
102
+ * What to render for this reader, and what to file their signals under.
103
+ *
104
+ * The one call a render path makes once a deployment has segments: it answers
105
+ * the live page composed with the forms this reader's segments earn, the
106
+ * segment's name for the page's signals, and — where the forms could not be
107
+ * applied — why.
108
+ *
109
+ * **A form that cannot be applied costs the reader their segment, not their
110
+ * page.** The two properties either side of this are both worth keeping and
111
+ * they pull apart exactly here. A pull that fails costs freshness and never the
112
+ * page (0358 clause 4), so there is always something to render. A composition
113
+ * refuses rather than falling back to the base (0263 clause 4), because a
114
+ * reader served the base whose page views are filed under `aud_eu` makes the
115
+ * comparison between two segments a comparison between one segment's form and
116
+ * another segment's *name over the base*.
117
+ *
118
+ * Dropping the audience keeps both: the reader gets the base page, their
119
+ * signals say what they were actually shown, and the deployment's figures stay
120
+ * a comparison of forms readers were served. The refusal is handed back rather
121
+ * than swallowed because a segment whose form has gone stale is a thing
122
+ * somebody must be told about — it is silent otherwise, and silently serving
123
+ * the base is the state 0263 clause 4 refuses.
124
+ *
125
+ * A deployment with no segments, a reader the rules do not match, and a server
126
+ * that has never pulled all answer the same way: the page, and no segment.
127
+ *
128
+ * **The pin is applied first, and the segment is chosen against the version it
129
+ * chose** (0383, *Audiences*). The rules sort the reader as they do now — they
130
+ * read the context, never the page — but the forms were authored against the
131
+ * version in `pages`, so a form that does not apply to the version a pinned
132
+ * reader was given is refused by the composition, and this answers that reader
133
+ * the version they were pinned to without their segment's form. That is the
134
+ * same trade `refusal` already describes one dimension across: the reader keeps
135
+ * their page, their signals say they were shown the base, and the deployment is
136
+ * told why.
137
+ */
138
+ export const pageForReader = (held, built, context, pin) => {
139
+ const base = livePageOf(held, built.treeId, pin) ?? built;
140
+ const audience = segmentOf(held, built.treeId, context);
141
+ const forms = held.forms.get(built.treeId) ?? [];
142
+ if (forms.length === 0)
143
+ return { tree: base, audience, refusal: undefined };
144
+ const composed = composeTreeForContext(base, overlayFor(held.rules.get(built.treeId) ?? [], forms), context);
145
+ return composed.ok
146
+ ? { tree: composed.value.tree, audience, refusal: undefined }
147
+ : { tree: base, audience: undefined, refusal: composed.error };
148
+ };
149
+ /** Every live page held, in the order the door answered them. */
150
+ export const livePagesHeld = (held) => [...held.pages.values()];
151
+ /**
152
+ * Whether the server is drawing on pages the door confirmed, rather than on
153
+ * nothing.
154
+ *
155
+ * A site holding pages after ten failed pulls is still serving Loom's pages,
156
+ * which is the behaviour clause 4 asks for and not a state worth hiding. What
157
+ * `failures` is for is saying so out loud in a log; what this is for is the
158
+ * simpler question of whether the door has ever been reached.
159
+ */
160
+ export const isPulling = (held) => held.pulledAt !== undefined;
161
+ //# sourceMappingURL=pages.js.map
@@ -0,0 +1,147 @@
1
+ /**
2
+ * One pull of a project's live pages, and what it does to the pages a server
3
+ * already holds.
4
+ *
5
+ * The request is deliberately the smallest thing that can be made: a `GET`, the
6
+ * project's key as a bearer, the tag of what is held, and no query at all. A
7
+ * request that could say which reader it was for, or which audience, would put
8
+ * Loom back in the render path (0262) — so the client cannot build one. The
9
+ * door refuses a query as well, and both halves saying so is the point: the
10
+ * property does not rest on either side being well behaved.
11
+ *
12
+ * The work is split in two on purpose. `pullLivePages` makes the request and
13
+ * reads the answer, and is the only part that touches a network. Deciding what
14
+ * the answer means for what is held is `withPullOutcome`, which is a pure
15
+ * function of the two — so every branch a server can take, including the ones
16
+ * that only happen when the door misbehaves, is reachable in a test without a
17
+ * running Loom.
18
+ */
19
+ import type { AudienceForm } from "../audience/compose.js";
20
+ import { type AudienceRule } from "../audience/rule.js";
21
+ import { type TreeId } from "../ids.js";
22
+ import { type Result } from "../result.js";
23
+ import { type LoomTree } from "../tree/tree.js";
24
+ import { type LivePages } from "./pages.js";
25
+ import { type LiveWindow } from "./window.js";
26
+ /** The one path the client asks for, so no customer's configuration holds it. */
27
+ export declare const LIVE_PAGES_PATH = "/api/pages/live";
28
+ /** `10s`. A pull nobody is waiting for, with a ceiling well inside the interval. */
29
+ export declare const DEFAULT_PULL_CEILING_MS = 10000;
30
+ /**
31
+ * Why a pull did not move what the server holds.
32
+ *
33
+ * The reason is what a log is read for, and the five are the five a deployment
34
+ * acts on differently: its configuration is wrong, Loom is unreachable, Loom is
35
+ * slow, its key is not accepted, or the answer was not one the client can
36
+ * believe. None of them costs the page.
37
+ */
38
+ export type SitePullFailure = {
39
+ readonly reason: "unconfigured" | "unreachable" | "expired" | "refused" | "unreadable";
40
+ readonly detail: string;
41
+ readonly status?: number;
42
+ };
43
+ /**
44
+ * One page's segment rules as the door answers them: the page, and its list in
45
+ * the order the portal set (0371).
46
+ */
47
+ export type LivePageRules = {
48
+ readonly treeId: TreeId;
49
+ readonly rules: readonly AudienceRule[];
50
+ };
51
+ /**
52
+ * One page's segment forms as the door answers them: the page, and a delta per
53
+ * segment that has one, each authored against the revision of the page it
54
+ * arrives beside (0371).
55
+ */
56
+ export type LivePageForms = {
57
+ readonly treeId: TreeId;
58
+ readonly forms: readonly AudienceForm[];
59
+ };
60
+ /** What one pull did: brought pages and their rules, confirmed the ones held, or failed. */
61
+ export type SitePullOutcome = {
62
+ readonly kind: "fresh";
63
+ readonly pages: readonly LoomTree[];
64
+ readonly rules: readonly LivePageRules[];
65
+ readonly forms: readonly LivePageForms[];
66
+ readonly window: LiveWindow;
67
+ readonly tag: string | undefined;
68
+ } | {
69
+ readonly kind: "unchanged";
70
+ } | {
71
+ readonly kind: "failed";
72
+ readonly failure: SitePullFailure;
73
+ };
74
+ /**
75
+ * The shape of `fetch` a pull needs, which is narrower than the global.
76
+ *
77
+ * Narrower so that a test can be a function rather than a server, and so that a
78
+ * host behind a proxy can hand over its own client without implementing the
79
+ * parts of `fetch` nothing here calls.
80
+ */
81
+ export type PullFetch = (url: string, init: {
82
+ readonly method: "GET";
83
+ readonly headers: Readonly<Record<string, string>>;
84
+ readonly signal: AbortSignal;
85
+ readonly cache: "no-store";
86
+ }) => Promise<Response>;
87
+ export type PullLivePagesOptions = {
88
+ /**
89
+ * Where this project's Loom deployment is, as an origin — `https://loom.example.com`.
90
+ * The path is this module's, so a project's configuration never carries one.
91
+ */
92
+ readonly deployment: string;
93
+ /**
94
+ * The project's public key, the one its pages already post signals with
95
+ * (0298). Opaque here: what a key may look like is the door's to say, and a
96
+ * second spelling of the rule in the client would be a second place to be
97
+ * wrong.
98
+ */
99
+ readonly key: string;
100
+ /** How long to wait for the door. `DEFAULT_PULL_CEILING_MS` when unset. */
101
+ readonly ceilingMs?: number;
102
+ /** `globalThis.fetch` unless a host hands over its own. */
103
+ readonly fetch?: PullFetch;
104
+ };
105
+ /**
106
+ * The URL a pull asks for, which by construction carries no query and no
107
+ * fragment.
108
+ *
109
+ * A configured deployment can hold either, by a copied address or a trailing
110
+ * `?`, and a query would be refused by the door with a `400` once a minute for
111
+ * ever. Clearing both here means the one thing the client must not send is not
112
+ * something it can send.
113
+ *
114
+ * The path is appended to whatever path the deployment carries rather than
115
+ * resolved against its origin, so a Loom served under a path keeps it:
116
+ * resolving `/api/pages/live` against `https://example.com/loom` would quietly
117
+ * drop the `/loom`.
118
+ */
119
+ export declare const livePagesUrlOf: (deployment: string) => Result<URL, SitePullFailure>;
120
+ /**
121
+ * Asks the door once, and says what the answer was.
122
+ *
123
+ * It never throws and never rejects: a network that is down, a Loom that is
124
+ * slow and a door answering something unreadable are all outcomes, because a
125
+ * caller that has to catch has a path on which the page is lost (0358 clause
126
+ * 4).
127
+ */
128
+ export declare const pullLivePages: (options: PullLivePagesOptions, held: LivePages) => Promise<SitePullOutcome>;
129
+ /**
130
+ * What the server holds after an outcome: the pure half, and the only place the
131
+ * holding changes.
132
+ *
133
+ * A failed pull returns the pages untouched with one more failure against them,
134
+ * which is clause 4 of the decision behind the pull (0358) as a line of code:
135
+ * freshness is what is lost, never the page. A tag moves only with the pages it
136
+ * names, so what is sent back as `If-None-Match` always describes what is held,
137
+ * and the rules move only with the pages they sort readers of (0371 clause 4).
138
+ *
139
+ * The window moves with them for the same reason, and it has to: its `number`
140
+ * is what a reader with no pin is pinned to and its `held` versions are of the
141
+ * pages beside it, so a window from one pull over another pull's pages would
142
+ * pin new readers to a state those pages were never in (0383 clause 5).
143
+ */
144
+ export declare const withPullOutcome: (held: LivePages, outcome: SitePullOutcome, at: number) => LivePages;
145
+ /** One sentence for a log, naming what failed and what it cost. */
146
+ export declare const describeSitePullFailure: (failure: SitePullFailure) => string;
147
+ //# sourceMappingURL=pull.d.ts.map