@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,217 @@
1
+ /**
2
+ * Custody of the two things a deployment needs to serve one page to more than
3
+ * one audience: the **rules** that sort readers, and the **form** each audience
4
+ * earns.
5
+ *
6
+ * [0359](../../decisions/0359-an-audience-rule-is-a-conjunction-of-scalar-clauses-and-a-composed-page-is-a-projection-of-a-revision.md)
7
+ * clause 6 left this out on purpose — *`composingTreeSourceFromStore` takes an
8
+ * `AudienceOverlaySource`, a seam and not a table* — so the composition could
9
+ * be built, tested and reviewed without a schema change under it. This is the
10
+ * table the seam was waiting for, and it is 0263's store dimension.
11
+ *
12
+ * **The rules are a log and the forms are rows, and the asymmetry is the
13
+ * decision in this file.** A rule decides which readers get which form, so
14
+ * editing one changes what every reader in that audience sees — without
15
+ * touching the page, its delta, or its log. Kept as a mutable row, that change
16
+ * would leave **no record anywhere**: the one thing Loom exists to make
17
+ * impossible. So a rule list is appended to, attributed and dense, exactly as
18
+ * the policy log is and for the same reason (0200). A form is a document being
19
+ * worked on; its history is the proposal that produced it, and a second log of
20
+ * every keystroke on it would be a record of drafting rather than of deciding.
21
+ *
22
+ * Nothing here evaluates a rule. `rule.ts` does that, in the customer's own
23
+ * process, over a context that never leaves it (0262) — this module only keeps
24
+ * what that evaluation is handed.
25
+ */
26
+ import { z } from "zod";
27
+ import { treeIdSchema } from "../ids.js";
28
+ import { clampLimit } from "../paging.js";
29
+ import { err, mapResult, ok } from "../result.js";
30
+ import { treeDeltaSchema } from "../tree/delta.js";
31
+ import { audienceIdSchema } from "./audience.js";
32
+ import { audienceRuleSchema } from "./rule.js";
33
+ const audienceRuleRevisionSchema = z.object({
34
+ treeId: treeIdSchema,
35
+ revision: z.number().int().positive(),
36
+ /**
37
+ * Empty is a real state and the one a page reaches by having its last rule
38
+ * removed: *this page is served to everybody the same way, and somebody
39
+ * decided that*. The alternative spelling — delete the row — is the spelling
40
+ * that cannot be attributed.
41
+ */
42
+ rules: z.array(audienceRuleSchema),
43
+ actor: z.string().min(1),
44
+ recordedAt: z.string().datetime(),
45
+ });
46
+ const audienceFormWithdrawalSchema = z.object({
47
+ actor: z.string().min(1),
48
+ at: z.string().datetime(),
49
+ });
50
+ const storedAudienceFormSchema = z.object({
51
+ treeId: treeIdSchema,
52
+ audienceId: audienceIdSchema,
53
+ delta: treeDeltaSchema,
54
+ actor: z.string().min(1),
55
+ authoredAt: z.string().datetime(),
56
+ /**
57
+ * `.optional()` rather than `.nullable()`, because the two backends spell
58
+ * *not withdrawn* differently — a `Map` holds no key, a column holds `NULL` —
59
+ * and the shape the contract compares is the one neither of them can skew.
60
+ * The Postgres reader maps its `NULL` to absent at the row, so only one
61
+ * spelling reaches here.
62
+ */
63
+ withdrawn: audienceFormWithdrawalSchema.optional(),
64
+ });
65
+ export const describeAudienceOverlayError = (error) => {
66
+ switch (error.code) {
67
+ case "out-of-date":
68
+ return `${error.treeId}'s rules moved on: this edit is of revision ${error.expected}, the current one is ${error.current}`;
69
+ case "tree-mismatch":
70
+ return `a form for ${error.treeId} cannot carry a delta for ${error.delta}`;
71
+ case "unreadable":
72
+ return `${error.treeId}'s stored audience overlay did not parse: ${error.detail}`;
73
+ case "unavailable":
74
+ return `storage is unavailable: ${error.detail}`;
75
+ }
76
+ };
77
+ /**
78
+ * A row on the way out, checked rather than cast — the boundary every stored
79
+ * shape in this repository crosses the same way. These two outlive the code
80
+ * that wrote them by more than most: a rule is edited rarely and read on every
81
+ * request for as long as the page is published.
82
+ */
83
+ export const parseAudienceRuleRevision = (row, treeId) => {
84
+ const parsed = audienceRuleRevisionSchema.safeParse(row);
85
+ return parsed.success
86
+ ? ok(parsed.data)
87
+ : err({
88
+ code: "unreadable",
89
+ treeId,
90
+ detail: parsed.error.issues[0]?.message ?? "invalid",
91
+ });
92
+ };
93
+ export const parseStoredAudienceForm = (row, treeId) => {
94
+ const parsed = storedAudienceFormSchema.safeParse(row);
95
+ /**
96
+ * `withdrawn` is restated rather than spread through, because the schema's
97
+ * `.optional()` makes it an absent key and `StoredAudienceForm` makes it a
98
+ * present one holding `undefined`. Under `exactOptionalPropertyTypes` those
99
+ * are two different types, and the one every reader of a form tests with
100
+ * `=== undefined` is this one.
101
+ */
102
+ return parsed.success
103
+ ? ok({ ...parsed.data, withdrawn: parsed.data.withdrawn })
104
+ : err({
105
+ code: "unreadable",
106
+ treeId,
107
+ detail: parsed.error.issues[0]?.message ?? "invalid",
108
+ });
109
+ };
110
+ /**
111
+ * How much of a page's rule history one read answers.
112
+ *
113
+ * Bounded, because every read in this store is (0025's rule, as `store.ts`
114
+ * states it: *no caller can ask a store for everything it holds, whether by
115
+ * naming a large limit or by naming none*). Unpaged, which `ProjectStore.list`
116
+ * already is: a page's rules are edited rarely, the newest edits are the ones a
117
+ * screen shows, and a cursor is machinery that would be written now and first
118
+ * exercised by nobody. **Reaching past the limit is not offered** — the rows are
119
+ * there, and the read that walks them is for whoever first needs it.
120
+ */
121
+ export const DEFAULT_AUDIENCE_RULE_HISTORY_LIMIT = 25;
122
+ export const MAX_AUDIENCE_RULE_HISTORY_LIMIT = 100;
123
+ export const clampAudienceRuleHistoryLimit = (limit) => clampLimit(limit, {
124
+ fallback: DEFAULT_AUDIENCE_RULE_HISTORY_LIMIT,
125
+ max: MAX_AUDIENCE_RULE_HISTORY_LIMIT,
126
+ });
127
+ /**
128
+ * Whether two rule lists say the same thing.
129
+ *
130
+ * **Order-sensitive, and that is the point**: 0359 clause 3 makes the order the
131
+ * precedence, so two lists holding the same rules in a different order are two
132
+ * different deployments and recording the second one is an edit. Compared by
133
+ * `JSON.stringify` rather than field by field because a rule is a closed JSON
134
+ * shape — `audienceRuleSchema` admits nothing a stringify would miss — and the
135
+ * alternative is a deep-equality walk that grows a case every time a clause
136
+ * does.
137
+ */
138
+ const sameRules = (held, offered) => JSON.stringify(held) === JSON.stringify(offered);
139
+ /**
140
+ * What a `record` call should do, given the head it would append after.
141
+ *
142
+ * Shared rather than written per backend, for the reason `recordOutcomeOf` is:
143
+ * the staleness check and *what counts as unchanged* are the contract, not an
144
+ * implementation detail, so two backends cannot disagree about whether a save
145
+ * with nothing in it is an edit.
146
+ */
147
+ export const audienceRulesOutcomeOf = (treeId, request, head) => {
148
+ const current = head?.revision ?? 0;
149
+ if (request.expectedRevision !== undefined && request.expectedRevision !== current) {
150
+ return err({
151
+ code: "out-of-date",
152
+ treeId,
153
+ expected: request.expectedRevision,
154
+ current,
155
+ });
156
+ }
157
+ if (head !== undefined && sameRules(head.rules, request.rules)) {
158
+ return ok({ outcome: "unchanged", revision: head });
159
+ }
160
+ /**
161
+ * Parsed rather than assembled, so a revision this store would accept and the
162
+ * database would refuse cannot be told apart by which one you used. It is also
163
+ * where an actor nobody named and a stamp that is not an instant are refused —
164
+ * both are caller-supplied strings, and both are load-bearing on a record of
165
+ * who changed who sees what.
166
+ */
167
+ return mapResult(parseAudienceRuleRevision({
168
+ treeId,
169
+ revision: current + 1,
170
+ rules: request.rules,
171
+ actor: request.actor,
172
+ recordedAt: request.recordedAt,
173
+ }, treeId), (revision) => ({ outcome: "recorded", revision }));
174
+ };
175
+ /**
176
+ * The overlay a reader of the two halves assembles, shared so the backends
177
+ * cannot disagree about what *whole* means.
178
+ */
179
+ export const audienceOverlayOf = (head, forms) => ({ rules: head?.rules ?? [], forms });
180
+ /**
181
+ * The forms the render path is given: every row that has not been withdrawn,
182
+ * without its attribution.
183
+ *
184
+ * **Shared for the reason `audienceRulesOutcomeOf` is.** Which rows compose is
185
+ * the contract and not an implementation detail, and a backend that answered a
186
+ * withdrawn form would serve a segment a change somebody undid — the exact
187
+ * fault 0403 exists to close, arriving as a disagreement between two stores
188
+ * that are each green against their own expectations.
189
+ */
190
+ export const servedFormsOf = (stored) => stored
191
+ .filter((form) => form.withdrawn === undefined)
192
+ .map(({ audienceId, delta }) => ({ audienceId, delta }));
193
+ /**
194
+ * The listing a screen gets: **every** row, withdrawn ones included, with the
195
+ * deltas left behind (0376).
196
+ */
197
+ export const audienceFormListingsOf = (stored) => stored.map(({ audienceId, delta, actor, authoredAt, withdrawn }) => ({
198
+ audienceId,
199
+ baseRevision: delta.baseRevision,
200
+ actor,
201
+ authoredAt,
202
+ withdrawn,
203
+ }));
204
+ /**
205
+ * The row a withdrawal leaves, given the one it found.
206
+ *
207
+ * Shared so neither backend can decide on its own that a withdrawal also
208
+ * rewrites `actor` or `authoredAt`. It does not: those two say who authored the
209
+ * form, and overwriting them with the person who withdrew it would lose the
210
+ * attribution 0376 clause 1 keeps — and make *who wrote this* unanswerable the
211
+ * moment somebody took it out of service.
212
+ */
213
+ export const withdrawnFormOf = (held, request) => ({
214
+ ...held,
215
+ withdrawn: { actor: request.actor, at: request.withdrawnAt },
216
+ });
217
+ //# sourceMappingURL=overlay-store.js.map
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Which audiences a reader is in, decided in the customer's own process.
3
+ *
4
+ * [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
5
+ * clause 1 says an audience is a **predicate over the opaque render context**,
6
+ * and clause 4 says the match happens in the data plane, per request, with
7
+ * nothing about the reader leaving it. This module is that predicate and that
8
+ * match, and it is the half of an audience `audience.ts` deliberately does not
9
+ * hold.
10
+ *
11
+ * **It does not contradict 0284, and the distinction is the whole design.**
12
+ * That record says the predicate *lives in the control plane's rules* and that
13
+ * *no column holds a rule, an expression, a context key or a matched value* —
14
+ * both of which are about where a rule is **authored and stored**. A rule is
15
+ * written in the portal and kept there; it is **shipped** to the customer's app
16
+ * and **evaluated** there, beside the base tree, which is the only place it can
17
+ * be evaluated without a request to Loom in front of every page view (0262).
18
+ * Nothing here stores a rule and nothing here learns what one means: a rule
19
+ * arrives as data, is read once, and answers a list of ids.
20
+ *
21
+ * So the control plane says *what `aud_eu` is*; this says *whether this reader
22
+ * is in it*; and `audience.ts` says *what the id looks like once both are done*.
23
+ */
24
+ import { z } from "zod";
25
+ import type { JsonObject } from "../json.js";
26
+ import { type AudienceId } from "./audience.js";
27
+ /**
28
+ * The values a clause may compare against.
29
+ *
30
+ * JSON's scalars and no more. A context key holding an object or an array never
31
+ * matches — stated here rather than left to `===`, which would answer `false`
32
+ * for two structurally equal objects and look like a rule that does not work
33
+ * rather than one that was never offered. A host with structure in its context
34
+ * flattens it into keys, which is what a rule can read.
35
+ */
36
+ export type AudienceValue = string | number | boolean | null;
37
+ /**
38
+ * One context key, and the values of it this clause accepts.
39
+ *
40
+ * `anyOf` rather than a single value because *locale is one of en-GB, en-IE* is
41
+ * the ordinary case and the alternative is one audience per locale, each with
42
+ * its own copy of the same delta — the maintenance failure 0263 rejected a tree
43
+ * per variant over, arriving one level down.
44
+ */
45
+ export type AudienceClause = {
46
+ readonly key: string;
47
+ /** Non-empty: a clause accepting nothing is a rule that can never match. */
48
+ readonly anyOf: readonly AudienceValue[];
49
+ };
50
+ export declare const audienceClauseSchema: z.ZodObject<{
51
+ key: z.ZodString;
52
+ anyOf: z.ZodArray<z.ZodType<AudienceValue, z.ZodTypeDef, AudienceValue>, "many">;
53
+ }, "strip", z.ZodTypeAny, {
54
+ key: string;
55
+ anyOf: AudienceValue[];
56
+ }, {
57
+ key: string;
58
+ anyOf: AudienceValue[];
59
+ }>;
60
+ /**
61
+ * An audience, and what puts a reader in it.
62
+ *
63
+ * The clauses are a **conjunction** and there is no `or` at this level, because
64
+ * two rules both matching is already the answer to *or* — `audiencesFor`
65
+ * returns every audience that matched, and a reader in two audiences earns both
66
+ * deltas. A rule language with its own `or` would be a second way to say what
67
+ * the list of rules already says, and a third to maintain.
68
+ *
69
+ * **At least one clause.** A rule matching every reader is `aud_everyone`,
70
+ * which the base tree already serves by being the base; a second way to say
71
+ * *everyone* is a delta that silently applies to a deployment that thought it
72
+ * had none.
73
+ */
74
+ export type AudienceRule = {
75
+ readonly audienceId: AudienceId;
76
+ readonly clauses: readonly AudienceClause[];
77
+ };
78
+ export declare const audienceRuleSchema: z.ZodObject<{
79
+ audienceId: z.ZodBranded<z.ZodString, "AudienceId">;
80
+ clauses: z.ZodArray<z.ZodObject<{
81
+ key: z.ZodString;
82
+ anyOf: z.ZodArray<z.ZodType<AudienceValue, z.ZodTypeDef, AudienceValue>, "many">;
83
+ }, "strip", z.ZodTypeAny, {
84
+ key: string;
85
+ anyOf: AudienceValue[];
86
+ }, {
87
+ key: string;
88
+ anyOf: AudienceValue[];
89
+ }>, "many">;
90
+ }, "strip", z.ZodTypeAny, {
91
+ audienceId: string & z.BRAND<"AudienceId">;
92
+ clauses: {
93
+ key: string;
94
+ anyOf: AudienceValue[];
95
+ }[];
96
+ }, {
97
+ audienceId: string;
98
+ clauses: {
99
+ key: string;
100
+ anyOf: AudienceValue[];
101
+ }[];
102
+ }>;
103
+ export declare const ruleMatches: (rule: AudienceRule, context: JsonObject) => boolean;
104
+ /**
105
+ * Every audience this reader is in, in the order the rules were given.
106
+ *
107
+ * **The order is the deployment's and it is load-bearing**, because two deltas
108
+ * reaching the same node resolve by the order they are applied in — so it must
109
+ * be something a deployment sets and reads back, rather than something a map's
110
+ * iteration or an id's spelling decides.
111
+ *
112
+ * An audience named by two matching rules appears **once, at its first
113
+ * position**. Its delta is one delta; applying it twice would double whatever
114
+ * it inserted, and the only reason two rules name one audience is that the
115
+ * deployment wrote two ways into the same group.
116
+ *
117
+ * A reader with no context is in no audience, which is the same answer as a
118
+ * context nothing matches: the base tree, unchanged.
119
+ */
120
+ export declare const audiencesFor: (rules: readonly AudienceRule[], context: JsonObject | undefined) => readonly AudienceId[];
121
+ //# sourceMappingURL=rule.d.ts.map
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Which audiences a reader is in, decided in the customer's own process.
3
+ *
4
+ * [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
5
+ * clause 1 says an audience is a **predicate over the opaque render context**,
6
+ * and clause 4 says the match happens in the data plane, per request, with
7
+ * nothing about the reader leaving it. This module is that predicate and that
8
+ * match, and it is the half of an audience `audience.ts` deliberately does not
9
+ * hold.
10
+ *
11
+ * **It does not contradict 0284, and the distinction is the whole design.**
12
+ * That record says the predicate *lives in the control plane's rules* and that
13
+ * *no column holds a rule, an expression, a context key or a matched value* —
14
+ * both of which are about where a rule is **authored and stored**. A rule is
15
+ * written in the portal and kept there; it is **shipped** to the customer's app
16
+ * and **evaluated** there, beside the base tree, which is the only place it can
17
+ * be evaluated without a request to Loom in front of every page view (0262).
18
+ * Nothing here stores a rule and nothing here learns what one means: a rule
19
+ * arrives as data, is read once, and answers a list of ids.
20
+ *
21
+ * So the control plane says *what `aud_eu` is*; this says *whether this reader
22
+ * is in it*; and `audience.ts` says *what the id looks like once both are done*.
23
+ */
24
+ import { z } from "zod";
25
+ import { audienceIdSchema } from "./audience.js";
26
+ const audienceValueSchema = z.union([
27
+ z.string(),
28
+ z.number().finite(),
29
+ z.boolean(),
30
+ z.null(),
31
+ ]);
32
+ export const audienceClauseSchema = z.object({
33
+ key: z.string().min(1),
34
+ anyOf: z.array(audienceValueSchema).min(1),
35
+ });
36
+ export const audienceRuleSchema = z.object({
37
+ audienceId: audienceIdSchema,
38
+ clauses: z.array(audienceClauseSchema).min(1),
39
+ });
40
+ const scalar = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean"
41
+ ? value
42
+ : undefined;
43
+ /**
44
+ * Whether one clause is satisfied by the context.
45
+ *
46
+ * An absent key does not match, and neither does a key holding structure. Both
47
+ * are *this reader is not in this audience* rather than an error: a context is
48
+ * the host's to shape and a rule is written against the shape the host says it
49
+ * has, so a mismatch is a rule that does not apply rather than a request that
50
+ * cannot be served.
51
+ */
52
+ const clauseMatches = (clause, context) => {
53
+ const value = scalar(context[clause.key]);
54
+ return value === undefined ? false : clause.anyOf.includes(value);
55
+ };
56
+ export const ruleMatches = (rule, context) => rule.clauses.every((clause) => clauseMatches(clause, context));
57
+ /**
58
+ * Every audience this reader is in, in the order the rules were given.
59
+ *
60
+ * **The order is the deployment's and it is load-bearing**, because two deltas
61
+ * reaching the same node resolve by the order they are applied in — so it must
62
+ * be something a deployment sets and reads back, rather than something a map's
63
+ * iteration or an id's spelling decides.
64
+ *
65
+ * An audience named by two matching rules appears **once, at its first
66
+ * position**. Its delta is one delta; applying it twice would double whatever
67
+ * it inserted, and the only reason two rules name one audience is that the
68
+ * deployment wrote two ways into the same group.
69
+ *
70
+ * A reader with no context is in no audience, which is the same answer as a
71
+ * context nothing matches: the base tree, unchanged.
72
+ */
73
+ export const audiencesFor = (rules, context) => {
74
+ if (context === undefined)
75
+ return [];
76
+ return [...new Set(rules.filter((rule) => ruleMatches(rule, context)).map((rule) => rule.audienceId))];
77
+ };
78
+ //# sourceMappingURL=rule.js.map
@@ -1,8 +1,7 @@
1
1
  /**
2
- * The commands `loom` runs.
3
- *
4
- * Scaffolding a new project, and driving a proposal from the terminal against the
5
- * same runtime a server would use.
2
+ * The commands `loom` runs: scaffolding a new project, and adding a primitive
3
+ * to one. `parseArguments` takes `init`, `add primitive` and `--help`, and
4
+ * nothing here drives a proposal from the terminal.
6
5
  */
7
6
  export * from "./args.js";
8
7
  export * from "./filesystem.js";
package/dist/cli/index.js CHANGED
@@ -1,8 +1,7 @@
1
1
  /**
2
- * The commands `loom` runs.
3
- *
4
- * Scaffolding a new project, and driving a proposal from the terminal against the
5
- * same runtime a server would use.
2
+ * The commands `loom` runs: scaffolding a new project, and adding a primitive
3
+ * to one. `parseArguments` takes `init`, `add primitive` and `--help`, and
4
+ * nothing here drives a proposal from the terminal.
6
5
  */
7
6
  export * from "./args.js";
8
7
  export * from "./filesystem.js";
@@ -117,6 +117,25 @@ describe("the primitive registry", () => {
117
117
  expect(audit.notProbeable, describeRegistryAudit(audit)).toEqual([])
118
118
  })
119
119
 
120
+ /**
121
+ * The audit probes from the empty props bag, which the schema of a primitive
122
+ * requiring anything refuses. That is fine for one that hands its props
123
+ * straight to React and not for one that reads them — \`name.toUpperCase()\`
124
+ * on a prop nobody passed throws, and nothing above can judge a component
125
+ * that was never successfully called.
126
+ *
127
+ * The fix is not to loosen the schema. Hand the audit a props bag it accepts:
128
+ *
129
+ * \`\`\`ts
130
+ * auditRegistry(registry, { props: new Map([["your.primitive", [{ name: "Example" }]]]) })
131
+ * \`\`\`
132
+ */
133
+ it("has no primitives the audit could not configure", () => {
134
+ const audit = auditRegistry(registry)
135
+
136
+ expect(audit.notConfigured, describeRegistryAudit(audit)).toEqual([])
137
+ })
138
+
120
139
  /**
121
140
  * The one that stops a page rather than a portal: a component that throws on a
122
141
  * value its own schema accepts is one a tree the validator *accepted* can take
@@ -48,6 +48,14 @@ export interface DataAdapter<TParams = JsonObject, TAnswer extends JsonValue = J
48
48
  * be told about and a diagnostic says out loud; none of them is an exception
49
49
  * anyone catches.
50
50
  *
51
+ * `invalid-answer` and `unreadable-answer` are the other pair, and the two
52
+ * schemas behind them are why. An answer is refused by the **source's** own
53
+ * declaration, which is a claim about a host's database; or it satisfies that
54
+ * and is refused by the **primitive's**, which is a claim about what can go on a
55
+ * page (0180). The first is fixed by whoever owns the data and the second by
56
+ * whoever bound this node to that source, so a reader holding one code knows
57
+ * which file to open.
58
+ *
51
59
  * `no-such-source` and `not-resolved` are the pair worth keeping apart, and they
52
60
  * were one code until 12 September. An unregistered source is fixed in the
53
61
  * registry by whoever owns the data; a binding nothing resolved is fixed in the
@@ -58,7 +66,7 @@ export interface DataAdapter<TParams = JsonObject, TAnswer extends JsonValue = J
58
66
  * counting reasons.
59
67
  */
60
68
  export type DataUnavailable = {
61
- readonly reason: "no-such-source" | "not-resolved" | "invalid-params" | "invalid-answer" | "adapter-threw" | SourceFailure["code"];
69
+ readonly reason: "no-such-source" | "not-resolved" | "invalid-params" | "invalid-answer" | "unreadable-answer" | "adapter-threw" | SourceFailure["code"];
62
70
  readonly detail: string;
63
71
  };
64
72
  export declare const describeDataUnavailable: (unavailable: DataUnavailable) => string;
@@ -11,6 +11,8 @@ export const describeDataUnavailable = (unavailable) => {
11
11
  return `the params in the tree are not what the source accepts — ${unavailable.detail}`;
12
12
  case "invalid-answer":
13
13
  return `the source answered with something its own schema refuses — ${unavailable.detail}`;
14
+ case "unreadable-answer":
15
+ return `the source answered, and the primitive reading it says that is not a shape it can draw — ${unavailable.detail}`;
14
16
  case "adapter-threw":
15
17
  return `the source threw instead of answering — ${unavailable.detail}`;
16
18
  case "unavailable":
package/dist/data/plan.js CHANGED
Binary file
@@ -46,6 +46,28 @@ export declare const NO_DATA: NodeData;
46
46
  * is the kind of detail every caller gets right once and then forgets.
47
47
  */
48
48
  export declare const nodeDataOf: (answers: Readonly<Record<string, DataOutcome>>) => NodeData;
49
+ /**
50
+ * One planned request's answer: what a source gave back, or the named reason
51
+ * there is none.
52
+ *
53
+ * Named rather than left as its structure because it is half of a seam a host
54
+ * has to carry, and a loader cannot write `Result<JsonValue, DataUnavailable>`
55
+ * into its own return type without reaching past the entry points it is meant
56
+ * to use.
57
+ */
58
+ export type DataAnswer = Result<JsonValue, DataUnavailable>;
59
+ /**
60
+ * Every answer a resolution was built from, as plain data.
61
+ *
62
+ * Pairs and not a `ReadonlyMap`, because the only reason to publish these is
63
+ * that they travel. `JSON.stringify` turns a `Map` into `{}` and says nothing
64
+ * about it, so a host that serialised one would send an empty object, rebuild a
65
+ * resolution that answers nothing, and get a page of `data-unresolved`
66
+ * diagnostics with no hint that the answers were lost in transit rather than
67
+ * never fetched. An array of pairs is the shape every boundary already carries,
68
+ * and `new Map(answers)` is what `buildDataResolution` takes (0281).
69
+ */
70
+ export type DataAnswers = readonly (readonly [RequestKey, DataAnswer])[];
49
71
  /** What a node's data could not do, in the seam's own vocabulary. */
50
72
  export type NodeDataProblem = {
51
73
  readonly kind: "misdeclared";
@@ -87,5 +109,5 @@ export declare const EMPTY_DATA_RESOLUTION: DataResolution;
87
109
  * the same resolution, which is what makes the failure paths testable without a
88
110
  * fake adapter for each one.
89
111
  */
90
- export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, Result<JsonValue, DataUnavailable>>) => DataResolution;
112
+ export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, DataAnswer>) => DataResolution;
91
113
  //# sourceMappingURL=resolution.d.ts.map
@@ -2,7 +2,7 @@ import type { JsonObject } from "../json.js";
2
2
  import type { LoomTree } from "../tree/tree.js";
3
3
  import type { DataRegistry } from "./adapter.js";
4
4
  import { type DataPlan } from "./plan.js";
5
- import { type DataResolution } from "./resolution.js";
5
+ import { type DataAnswers, type DataResolution } from "./resolution.js";
6
6
  /**
7
7
  * The one step in serving a page that does IO.
8
8
  *
@@ -23,7 +23,7 @@ import { type DataResolution } from "./resolution.js";
23
23
  export type ResolveDataOptions = {
24
24
  readonly registry: DataRegistry;
25
25
  /** Passed through to every adapter — the render request's host context. */
26
- readonly context?: JsonObject;
26
+ readonly context?: JsonObject | undefined;
27
27
  /**
28
28
  * How long any one source is given, each independently of the others. Defaults
29
29
  * to `DEFAULT_SOURCE_CEILING_MS`; there is no way to wait forever (0140).
@@ -40,7 +40,34 @@ export type ResolveDataOptions = {
40
40
  * against a budget the others had already spent.
41
41
  */
42
42
  export declare const DEFAULT_SOURCE_CEILING_MS = 10000;
43
- export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<DataResolution>;
43
+ /**
44
+ * A resolution, and the answers it was built from.
45
+ *
46
+ * It *is* a `DataResolution`, so a caller that only renders reads nothing new
47
+ * and changes nothing. The extra field is for the host that fetches in one
48
+ * place and renders in another — the arrangement every React framework pushes a
49
+ * host towards, and the one this package could not serve: a resolution is two
50
+ * closures, and a closure cannot cross from a server component to a client one.
51
+ * The answers can, so the far side rebuilds from them:
52
+ *
53
+ * ```ts
54
+ * // where the fetching happens
55
+ * const { answers } = await resolveTreeData(tree, { registry })
56
+ * // wherever the walk happens, given the same tree
57
+ * const data = buildDataResolution(planTreeData(tree), new Map(answers))
58
+ * ```
59
+ *
60
+ * Re-planning rather than carrying the resolution is what keeps the one thing a
61
+ * caller must not get wrong inside the package: *which requests were asked*.
62
+ * Read off the plan it is a guess, and the obvious guess is wrong — a node whose
63
+ * declaration could not be read at all appears in `plan.problems` and never in
64
+ * `plan.bindings`, so a carrier built from the bindings drops exactly the nodes
65
+ * whose diagnostics matter most (0281).
66
+ */
67
+ export interface ResolvedData extends DataResolution {
68
+ readonly answers: DataAnswers;
69
+ }
70
+ export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<ResolvedData>;
44
71
  /** Plan and resolve in one step, for the ordinary caller that does both. */
45
- export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<DataResolution>;
72
+ export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<ResolvedData>;
46
73
  //# sourceMappingURL=resolve.d.ts.map
@@ -1,4 +1,5 @@
1
1
  import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
2
+ import { describeRegistered } from "../registered.js";
2
3
  import { err } from "../result.js";
3
4
  import { planTreeData, planIsEmpty } from "./plan.js";
4
5
  import { buildDataResolution, EMPTY_DATA_RESOLUTION, } from "./resolution.js";
@@ -17,20 +18,27 @@ const askOne = async (source, params, options) => {
17
18
  if (!registered) {
18
19
  return err({
19
20
  reason: "no-such-source",
20
- detail: `registered: ${options.registry.sources.map((entry) => entry.id).join(", ") || "none"}`,
21
+ detail: `registered: ${describeRegistered(source, options.registry.sources.map((entry) => entry.id))}`,
21
22
  });
22
23
  }
23
24
  const ceiling = ceilingOf(options.ceilingMs, DEFAULT_SOURCE_CEILING_MS);
24
25
  return withCeiling(ceiling, () => err({ reason: "unavailable", detail: `no answer in ${describeCeiling(ceiling)}` }), (signal) => registered.answer(params, options.context, signal));
25
26
  };
27
+ const NO_ANSWERS = Object.freeze([]);
28
+ /** The resolution of a plan that asks nothing, which asked nothing. */
29
+ const EMPTY_RESOLVED_DATA = Object.freeze({
30
+ ...EMPTY_DATA_RESOLUTION,
31
+ answers: NO_ANSWERS,
32
+ });
26
33
  export const resolveDataPlan = async (plan, options) => {
27
34
  if (planIsEmpty(plan))
28
- return EMPTY_DATA_RESOLUTION;
35
+ return EMPTY_RESOLVED_DATA;
29
36
  const answered = await Promise.all(plan.requests.map(async (request) => [
30
37
  request.key,
31
38
  await askOne(request.source, request.params, options),
32
39
  ]));
33
- return buildDataResolution(plan, new Map(answered));
40
+ const answers = Object.freeze(answered);
41
+ return { ...buildDataResolution(plan, new Map(answers)), answers };
34
42
  };
35
43
  /** Plan and resolve in one step, for the ordinary caller that does both. */
36
44
  export const resolveTreeData = async (tree, options) => resolveDataPlan(planTreeData(tree), options);
package/dist/ids.d.ts CHANGED
@@ -39,6 +39,16 @@ export interface IdFactory {
39
39
  readonly intentId: () => IntentId;
40
40
  readonly proposalId: () => ProposalId;
41
41
  }
42
+ /**
43
+ * The body of a random id, which is the part after the prefix.
44
+ *
45
+ * Exported because an application id and a project id are minted outside this
46
+ * module — by the control plane when somebody registers, rather than by an
47
+ * `IdFactory` during a render — and the alternative was either widening that
48
+ * interface with two members no renderer calls, or a second copy of this that
49
+ * drifts.
50
+ */
51
+ export declare const randomIdBody: () => string;
42
52
  export declare const randomIdFactory: IdFactory;
43
53
  /**
44
54
  * Deterministic ids for tests and for replaying a recorded session. Counters