@jam-overture/loom 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (401) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +743 -0
  3. package/dist/catalogue.d.ts +70 -0
  4. package/dist/catalogue.js +88 -0
  5. package/dist/cli/args.d.ts +17 -0
  6. package/dist/cli/args.js +83 -0
  7. package/dist/cli/filesystem.d.ts +15 -0
  8. package/dist/cli/filesystem.js +31 -0
  9. package/dist/cli/index.d.ts +12 -0
  10. package/dist/cli/index.js +12 -0
  11. package/dist/cli/main.d.ts +3 -0
  12. package/dist/cli/main.js +30 -0
  13. package/dist/cli/namespace.d.ts +40 -0
  14. package/dist/cli/namespace.js +40 -0
  15. package/dist/cli/plan.d.ts +84 -0
  16. package/dist/cli/plan.js +113 -0
  17. package/dist/cli/run.d.ts +17 -0
  18. package/dist/cli/run.js +75 -0
  19. package/dist/cli/templates.d.ts +43 -0
  20. package/dist/cli/templates.js +134 -0
  21. package/dist/closed-set.d.ts +34 -0
  22. package/dist/closed-set.js +34 -0
  23. package/dist/data/adapter.d.ts +123 -0
  24. package/dist/data/adapter.js +91 -0
  25. package/dist/data/binding.d.ts +48 -0
  26. package/dist/data/binding.js +39 -0
  27. package/dist/data/catalogue.d.ts +26 -0
  28. package/dist/data/catalogue.js +6 -0
  29. package/dist/data/index.d.ts +14 -0
  30. package/dist/data/index.js +14 -0
  31. package/dist/data/plan.d.ts +58 -0
  32. package/dist/data/plan.js +0 -0
  33. package/dist/data/resolution.d.ts +91 -0
  34. package/dist/data/resolution.js +96 -0
  35. package/dist/data/resolve.d.ts +46 -0
  36. package/dist/data/resolve.js +37 -0
  37. package/dist/data/source.d.ts +40 -0
  38. package/dist/data/source.js +45 -0
  39. package/dist/deadline.d.ts +57 -0
  40. package/dist/deadline.js +78 -0
  41. package/dist/frame/catalogue.d.ts +24 -0
  42. package/dist/frame/catalogue.js +5 -0
  43. package/dist/frame/index.d.ts +12 -0
  44. package/dist/frame/index.js +12 -0
  45. package/dist/frame/origin.d.ts +87 -0
  46. package/dist/frame/origin.js +114 -0
  47. package/dist/frame/resolution.d.ts +85 -0
  48. package/dist/frame/resolution.js +79 -0
  49. package/dist/grammar.d.ts +26 -0
  50. package/dist/grammar.js +28 -0
  51. package/dist/ids.d.ts +57 -0
  52. package/dist/ids.js +104 -0
  53. package/dist/index.d.ts +26 -0
  54. package/dist/index.js +26 -0
  55. package/dist/interactivity.d.ts +50 -0
  56. package/dist/interactivity.js +22 -0
  57. package/dist/interpretation/anthropic.d.ts +22 -0
  58. package/dist/interpretation/anthropic.js +76 -0
  59. package/dist/interpretation/client.d.ts +83 -0
  60. package/dist/interpretation/client.js +2 -0
  61. package/dist/interpretation/draft.d.ts +234 -0
  62. package/dist/interpretation/draft.js +84 -0
  63. package/dist/interpretation/index.d.ts +15 -0
  64. package/dist/interpretation/index.js +15 -0
  65. package/dist/interpretation/interpreter.d.ts +62 -0
  66. package/dist/interpretation/interpreter.js +151 -0
  67. package/dist/interpretation/materialize.d.ts +42 -0
  68. package/dist/interpretation/materialize.js +107 -0
  69. package/dist/interpretation/prompt.d.ts +229 -0
  70. package/dist/interpretation/prompt.js +285 -0
  71. package/dist/interpretation/render.d.ts +76 -0
  72. package/dist/interpretation/render.js +272 -0
  73. package/dist/interpretation/schema.d.ts +49 -0
  74. package/dist/interpretation/schema.js +131 -0
  75. package/dist/json.d.ts +35 -0
  76. package/dist/json.js +11 -0
  77. package/dist/paging.d.ts +60 -0
  78. package/dist/paging.js +49 -0
  79. package/dist/primitive-type.d.ts +32 -0
  80. package/dist/primitive-type.js +39 -0
  81. package/dist/render/addressing.d.ts +59 -0
  82. package/dist/render/addressing.js +60 -0
  83. package/dist/render/anchor.d.ts +105 -0
  84. package/dist/render/anchor.js +84 -0
  85. package/dist/render/behaviour-adjust.d.ts +62 -0
  86. package/dist/render/behaviour-adjust.js +78 -0
  87. package/dist/render/behaviour-copy.d.ts +53 -0
  88. package/dist/render/behaviour-copy.js +75 -0
  89. package/dist/render/behaviour-disclose.d.ts +74 -0
  90. package/dist/render/behaviour-disclose.js +77 -0
  91. package/dist/render/behaviour-present.d.ts +123 -0
  92. package/dist/render/behaviour-present.js +173 -0
  93. package/dist/render/behaviour.d.ts +243 -0
  94. package/dist/render/behaviour.js +284 -0
  95. package/dist/render/control.d.ts +81 -0
  96. package/dist/render/control.js +80 -0
  97. package/dist/render/decorative.d.ts +62 -0
  98. package/dist/render/decorative.js +2 -0
  99. package/dist/render/diagnostics.d.ts +260 -0
  100. package/dist/render/diagnostics.js +61 -0
  101. package/dist/render/disclosed.d.ts +37 -0
  102. package/dist/render/disclosed.js +37 -0
  103. package/dist/render/editable.d.ts +34 -0
  104. package/dist/render/editable.js +35 -0
  105. package/dist/render/frame.d.ts +42 -0
  106. package/dist/render/frame.js +31 -0
  107. package/dist/render/index.d.ts +35 -0
  108. package/dist/render/index.js +35 -0
  109. package/dist/render/inline-variables.d.ts +77 -0
  110. package/dist/render/inline-variables.js +220 -0
  111. package/dist/render/presented.d.ts +82 -0
  112. package/dist/render/presented.js +82 -0
  113. package/dist/render/primitive.d.ts +228 -0
  114. package/dist/render/primitive.js +36 -0
  115. package/dist/render/props.d.ts +48 -0
  116. package/dist/render/props.js +2 -0
  117. package/dist/render/reads.d.ts +73 -0
  118. package/dist/render/reads.js +45 -0
  119. package/dist/render/render.d.ts +164 -0
  120. package/dist/render/render.js +571 -0
  121. package/dist/render/request.d.ts +111 -0
  122. package/dist/render/request.js +60 -0
  123. package/dist/render/text.d.ts +91 -0
  124. package/dist/render/text.js +44 -0
  125. package/dist/render/theme.d.ts +61 -0
  126. package/dist/render/theme.js +52 -0
  127. package/dist/reserved-props.d.ts +35 -0
  128. package/dist/reserved-props.js +45 -0
  129. package/dist/result.d.ts +27 -0
  130. package/dist/result.js +30 -0
  131. package/dist/role.d.ts +71 -0
  132. package/dist/role.js +22 -0
  133. package/dist/runtime/analysis.d.ts +149 -0
  134. package/dist/runtime/analysis.js +187 -0
  135. package/dist/runtime/assessment.d.ts +35 -0
  136. package/dist/runtime/assessment.js +13 -0
  137. package/dist/runtime/disposition.d.ts +102 -0
  138. package/dist/runtime/disposition.js +59 -0
  139. package/dist/runtime/events.d.ts +187 -0
  140. package/dist/runtime/events.js +7 -0
  141. package/dist/runtime/gate.d.ts +43 -0
  142. package/dist/runtime/gate.js +169 -0
  143. package/dist/runtime/index.d.ts +27 -0
  144. package/dist/runtime/index.js +27 -0
  145. package/dist/runtime/intent.d.ts +60 -0
  146. package/dist/runtime/intent.js +36 -0
  147. package/dist/runtime/interpreter.d.ts +117 -0
  148. package/dist/runtime/interpreter.js +46 -0
  149. package/dist/runtime/inverse-interpreter.d.ts +90 -0
  150. package/dist/runtime/inverse-interpreter.js +56 -0
  151. package/dist/runtime/inverse.d.ts +87 -0
  152. package/dist/runtime/inverse.js +48 -0
  153. package/dist/runtime/narration.d.ts +24 -0
  154. package/dist/runtime/narration.js +36 -0
  155. package/dist/runtime/nesting.d.ts +31 -0
  156. package/dist/runtime/nesting.js +46 -0
  157. package/dist/runtime/pipeline.d.ts +124 -0
  158. package/dist/runtime/pipeline.js +178 -0
  159. package/dist/runtime/policy-fingerprint.d.ts +29 -0
  160. package/dist/runtime/policy-fingerprint.js +119 -0
  161. package/dist/runtime/policy-source.d.ts +42 -0
  162. package/dist/runtime/policy-source.js +8 -0
  163. package/dist/runtime/policy.d.ts +156 -0
  164. package/dist/runtime/policy.js +107 -0
  165. package/dist/runtime/proposal.d.ts +423 -0
  166. package/dist/runtime/proposal.js +109 -0
  167. package/dist/runtime/redirection.d.ts +53 -0
  168. package/dist/runtime/redirection.js +38 -0
  169. package/dist/runtime/repointing.d.ts +71 -0
  170. package/dist/runtime/repointing.js +0 -0
  171. package/dist/runtime/reversibility.d.ts +36 -0
  172. package/dist/runtime/reversibility.js +39 -0
  173. package/dist/runtime/stake-level.d.ts +33 -0
  174. package/dist/runtime/stake-level.js +58 -0
  175. package/dist/runtime/stakes.d.ts +47 -0
  176. package/dist/runtime/stakes.js +305 -0
  177. package/dist/runtime/vocabulary.d.ts +122 -0
  178. package/dist/runtime/vocabulary.js +87 -0
  179. package/dist/sdk/audit.d.ts +195 -0
  180. package/dist/sdk/audit.js +128 -0
  181. package/dist/sdk/catalogue.d.ts +37 -0
  182. package/dist/sdk/catalogue.js +16 -0
  183. package/dist/sdk/conformance.d.ts +342 -0
  184. package/dist/sdk/conformance.js +494 -0
  185. package/dist/sdk/copy.d.ts +105 -0
  186. package/dist/sdk/copy.js +90 -0
  187. package/dist/sdk/definition.d.ts +242 -0
  188. package/dist/sdk/definition.js +64 -0
  189. package/dist/sdk/index.d.ts +19 -0
  190. package/dist/sdk/index.js +19 -0
  191. package/dist/sdk/interactivity.d.ts +29 -0
  192. package/dist/sdk/interactivity.js +34 -0
  193. package/dist/sdk/pairings.d.ts +124 -0
  194. package/dist/sdk/pairings.js +81 -0
  195. package/dist/sdk/registry.d.ts +162 -0
  196. package/dist/sdk/registry.js +329 -0
  197. package/dist/sdk/selection.d.ts +46 -0
  198. package/dist/sdk/selection.js +24 -0
  199. package/dist/sdk/text.d.ts +100 -0
  200. package/dist/sdk/text.js +105 -0
  201. package/dist/sdk/vocabulary.d.ts +39 -0
  202. package/dist/sdk/vocabulary.js +36 -0
  203. package/dist/signals/broadcast.d.ts +134 -0
  204. package/dist/signals/broadcast.js +451 -0
  205. package/dist/signals/collect.d.ts +184 -0
  206. package/dist/signals/collect.js +196 -0
  207. package/dist/signals/deliver.d.ts +64 -0
  208. package/dist/signals/deliver.js +85 -0
  209. package/dist/signals/fold.d.ts +112 -0
  210. package/dist/signals/fold.js +76 -0
  211. package/dist/signals/index.d.ts +31 -0
  212. package/dist/signals/index.js +31 -0
  213. package/dist/signals/ingest.d.ts +51 -0
  214. package/dist/signals/ingest.js +70 -0
  215. package/dist/signals/intake.d.ts +149 -0
  216. package/dist/signals/intake.js +154 -0
  217. package/dist/signals/journal.d.ts +94 -0
  218. package/dist/signals/journal.js +11 -0
  219. package/dist/signals/kinds.d.ts +22 -0
  220. package/dist/signals/kinds.js +22 -0
  221. package/dist/signals/ledger.d.ts +46 -0
  222. package/dist/signals/ledger.js +81 -0
  223. package/dist/signals/memory.d.ts +17 -0
  224. package/dist/signals/memory.js +99 -0
  225. package/dist/signals/migrate.d.ts +27 -0
  226. package/dist/signals/migrate.js +78 -0
  227. package/dist/signals/postgres.d.ts +7 -0
  228. package/dist/signals/postgres.js +295 -0
  229. package/dist/signals/rollup.d.ts +142 -0
  230. package/dist/signals/rollup.js +0 -0
  231. package/dist/signals/schema.d.ts +534 -0
  232. package/dist/signals/schema.js +92 -0
  233. package/dist/signals/signal.d.ts +381 -0
  234. package/dist/signals/signal.js +150 -0
  235. package/dist/signals/tally.d.ts +70 -0
  236. package/dist/signals/tally.js +2 -0
  237. package/dist/signals/view.d.ts +51 -0
  238. package/dist/signals/view.js +54 -0
  239. package/dist/store/attribution.d.ts +125 -0
  240. package/dist/store/attribution.js +116 -0
  241. package/dist/store/database.d.ts +14 -0
  242. package/dist/store/database.js +2 -0
  243. package/dist/store/driver.d.ts +29 -0
  244. package/dist/store/driver.js +39 -0
  245. package/dist/store/errors.d.ts +56 -0
  246. package/dist/store/errors.js +37 -0
  247. package/dist/store/index.d.ts +16 -0
  248. package/dist/store/index.js +16 -0
  249. package/dist/store/memory.d.ts +3 -0
  250. package/dist/store/memory.js +115 -0
  251. package/dist/store/migrate.d.ts +54 -0
  252. package/dist/store/migrate.js +122 -0
  253. package/dist/store/postgres-holds.d.ts +4 -0
  254. package/dist/store/postgres-holds.js +192 -0
  255. package/dist/store/postgres.d.ts +8 -0
  256. package/dist/store/postgres.js +262 -0
  257. package/dist/store/replay.d.ts +94 -0
  258. package/dist/store/replay.js +82 -0
  259. package/dist/store/revert.d.ts +116 -0
  260. package/dist/store/revert.js +243 -0
  261. package/dist/store/schema.d.ts +371 -0
  262. package/dist/store/schema.js +78 -0
  263. package/dist/store/source.d.ts +23 -0
  264. package/dist/store/source.js +37 -0
  265. package/dist/store/store.d.ts +231 -0
  266. package/dist/store/store.js +52 -0
  267. package/dist/store/undone.d.ts +18 -0
  268. package/dist/store/undone.js +89 -0
  269. package/dist/submit/catalogue.d.ts +20 -0
  270. package/dist/submit/catalogue.js +5 -0
  271. package/dist/submit/declaration.d.ts +39 -0
  272. package/dist/submit/declaration.js +30 -0
  273. package/dist/submit/endpoint.d.ts +131 -0
  274. package/dist/submit/endpoint.js +160 -0
  275. package/dist/submit/index.d.ts +13 -0
  276. package/dist/submit/index.js +13 -0
  277. package/dist/submit/plan.d.ts +49 -0
  278. package/dist/submit/plan.js +47 -0
  279. package/dist/submit/resolution.d.ts +61 -0
  280. package/dist/submit/resolution.js +64 -0
  281. package/dist/submit/resolve.d.ts +45 -0
  282. package/dist/submit/resolve.js +36 -0
  283. package/dist/telemetry/calibration.d.ts +132 -0
  284. package/dist/telemetry/calibration.js +151 -0
  285. package/dist/telemetry/episode.d.ts +140 -0
  286. package/dist/telemetry/episode.js +272 -0
  287. package/dist/telemetry/event.d.ts +2310 -0
  288. package/dist/telemetry/event.js +405 -0
  289. package/dist/telemetry/index.d.ts +15 -0
  290. package/dist/telemetry/index.js +15 -0
  291. package/dist/telemetry/journal.d.ts +116 -0
  292. package/dist/telemetry/journal.js +11 -0
  293. package/dist/telemetry/memory.d.ts +24 -0
  294. package/dist/telemetry/memory.js +75 -0
  295. package/dist/telemetry/migrate.d.ts +26 -0
  296. package/dist/telemetry/migrate.js +40 -0
  297. package/dist/telemetry/postgres.d.ts +6 -0
  298. package/dist/telemetry/postgres.js +139 -0
  299. package/dist/telemetry/retention.d.ts +131 -0
  300. package/dist/telemetry/retention.js +217 -0
  301. package/dist/telemetry/schema.d.ts +113 -0
  302. package/dist/telemetry/schema.js +33 -0
  303. package/dist/telemetry/sink.d.ts +42 -0
  304. package/dist/telemetry/sink.js +61 -0
  305. package/dist/testing/contracts.d.ts +34 -0
  306. package/dist/testing/contracts.js +34 -0
  307. package/dist/testing/definitions.d.ts +15 -0
  308. package/dist/testing/definitions.js +48 -0
  309. package/dist/testing/doubles.d.ts +94 -0
  310. package/dist/testing/doubles.js +141 -0
  311. package/dist/testing/episode-harness.d.ts +49 -0
  312. package/dist/testing/episode-harness.js +65 -0
  313. package/dist/testing/filesystem.d.ts +17 -0
  314. package/dist/testing/filesystem.js +17 -0
  315. package/dist/testing/fixtures.d.ts +57 -0
  316. package/dist/testing/fixtures.js +84 -0
  317. package/dist/testing/hold-contract.d.ts +19 -0
  318. package/dist/testing/hold-contract.js +374 -0
  319. package/dist/testing/index.d.ts +41 -0
  320. package/dist/testing/index.js +41 -0
  321. package/dist/testing/journal-contract.d.ts +17 -0
  322. package/dist/testing/journal-contract.js +353 -0
  323. package/dist/testing/model-replies.d.ts +34 -0
  324. package/dist/testing/model-replies.js +101 -0
  325. package/dist/testing/primitives.d.ts +7 -0
  326. package/dist/testing/primitives.js +29 -0
  327. package/dist/testing/reader-signal-contract.d.ts +38 -0
  328. package/dist/testing/reader-signal-contract.js +318 -0
  329. package/dist/testing/row-security.d.ts +17 -0
  330. package/dist/testing/row-security.js +21 -0
  331. package/dist/testing/store-contract.d.ts +25 -0
  332. package/dist/testing/store-contract.js +500 -0
  333. package/dist/theme/apply.d.ts +17 -0
  334. package/dist/theme/apply.js +60 -0
  335. package/dist/theme/contrast.d.ts +197 -0
  336. package/dist/theme/contrast.js +259 -0
  337. package/dist/theme/derive.d.ts +77 -0
  338. package/dist/theme/derive.js +167 -0
  339. package/dist/theme/faces.d.ts +73 -0
  340. package/dist/theme/faces.js +119 -0
  341. package/dist/theme/font-packs.d.ts +25 -0
  342. package/dist/theme/font-packs.js +257 -0
  343. package/dist/theme/index.d.ts +20 -0
  344. package/dist/theme/index.js +20 -0
  345. package/dist/theme/lab.d.ts +30 -0
  346. package/dist/theme/lab.js +46 -0
  347. package/dist/theme/library.d.ts +114 -0
  348. package/dist/theme/library.js +300 -0
  349. package/dist/theme/measure.d.ts +144 -0
  350. package/dist/theme/measure.js +145 -0
  351. package/dist/theme/palettes.d.ts +64 -0
  352. package/dist/theme/palettes.js +497 -0
  353. package/dist/theme/registry.d.ts +59 -0
  354. package/dist/theme/registry.js +60 -0
  355. package/dist/theme/separation.d.ts +177 -0
  356. package/dist/theme/separation.js +203 -0
  357. package/dist/theme/style-presets.d.ts +60 -0
  358. package/dist/theme/style-presets.js +124 -0
  359. package/dist/theme/theme.d.ts +253 -0
  360. package/dist/theme/theme.js +171 -0
  361. package/dist/tree/apply.d.ts +16 -0
  362. package/dist/tree/apply.js +104 -0
  363. package/dist/tree/builders.d.ts +19 -0
  364. package/dist/tree/builders.js +20 -0
  365. package/dist/tree/compare.d.ts +68 -0
  366. package/dist/tree/compare.js +75 -0
  367. package/dist/tree/configuration.d.ts +25 -0
  368. package/dist/tree/configuration.js +108 -0
  369. package/dist/tree/delta.d.ts +288 -0
  370. package/dist/tree/delta.js +88 -0
  371. package/dist/tree/errors.d.ts +69 -0
  372. package/dist/tree/errors.js +34 -0
  373. package/dist/tree/identity.d.ts +117 -0
  374. package/dist/tree/identity.js +145 -0
  375. package/dist/tree/index.d.ts +21 -0
  376. package/dist/tree/index.js +21 -0
  377. package/dist/tree/inverse.d.ts +24 -0
  378. package/dist/tree/inverse.js +112 -0
  379. package/dist/tree/mutation.d.ts +18 -0
  380. package/dist/tree/mutation.js +49 -0
  381. package/dist/tree/naming.d.ts +4 -0
  382. package/dist/tree/naming.js +35 -0
  383. package/dist/tree/navigation.d.ts +38 -0
  384. package/dist/tree/navigation.js +83 -0
  385. package/dist/tree/node.d.ts +103 -0
  386. package/dist/tree/node.js +46 -0
  387. package/dist/tree/outline.d.ts +28 -0
  388. package/dist/tree/outline.js +10 -0
  389. package/dist/tree/tree.d.ts +83 -0
  390. package/dist/tree/tree.js +62 -0
  391. package/dist/write/commit.d.ts +124 -0
  392. package/dist/write/commit.js +234 -0
  393. package/dist/write/held.d.ts +674 -0
  394. package/dist/write/held.js +185 -0
  395. package/dist/write/index.d.ts +11 -0
  396. package/dist/write/index.js +11 -0
  397. package/dist/write/liveness.d.ts +132 -0
  398. package/dist/write/liveness.js +91 -0
  399. package/dist/write/revert.d.ts +79 -0
  400. package/dist/write/revert.js +134 -0
  401. package/package.json +160 -0
@@ -0,0 +1,26 @@
1
+ import type { CataloguedProp } from "../catalogue.js";
2
+ import type { DataRegistry } from "./adapter.js";
3
+ import type { SourceId } from "./source.js";
4
+ /**
5
+ * What a deployment can ask about, as data.
6
+ *
7
+ * The same projection `catalogueOf` makes for primitives, and it exists for the
8
+ * same reason: a model asked to put someone's services on their page can only
9
+ * name a source it was told about, and a source it was never told about is one
10
+ * it can only guess at. A registry is the allowlist; the catalogue is how the
11
+ * allowlist gets shown to whoever is choosing.
12
+ */
13
+ export type CataloguedSource = {
14
+ readonly id: SourceId;
15
+ /** One line, written by the source's author, about what it answers. */
16
+ readonly description: string;
17
+ /**
18
+ * Declared params, name-sorted. `undefined` when the declared schema is not an
19
+ * object schema and its keys therefore cannot be enumerated — unknown, which
20
+ * is not the same claim as "none".
21
+ */
22
+ readonly params: readonly CataloguedProp[] | undefined;
23
+ };
24
+ export type DataCatalogue = readonly CataloguedSource[];
25
+ export declare const dataCatalogue: (registry: DataRegistry) => DataCatalogue;
26
+ //# sourceMappingURL=catalogue.d.ts.map
@@ -0,0 +1,6 @@
1
+ export const dataCatalogue = (registry) => registry.sources.map((source) => ({
2
+ id: source.id,
3
+ description: source.description,
4
+ params: source.declaredParams,
5
+ }));
6
+ //# sourceMappingURL=catalogue.js.map
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Questions a tree asks and cannot answer itself.
3
+ *
4
+ * A node names a source, the source is resolved once per request before the render
5
+ * walk, and the answer — or a named reason there is none — reaches the primitive.
6
+ */
7
+ export * from "./adapter.js";
8
+ export * from "./binding.js";
9
+ export * from "./catalogue.js";
10
+ export * from "./plan.js";
11
+ export * from "./resolution.js";
12
+ export * from "./resolve.js";
13
+ export * from "./source.js";
14
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Questions a tree asks and cannot answer itself.
3
+ *
4
+ * A node names a source, the source is resolved once per request before the render
5
+ * walk, and the answer — or a named reason there is none — reaches the primitive.
6
+ */
7
+ export * from "./adapter.js";
8
+ export * from "./binding.js";
9
+ export * from "./catalogue.js";
10
+ export * from "./plan.js";
11
+ export * from "./resolution.js";
12
+ export * from "./resolve.js";
13
+ export * from "./source.js";
14
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,58 @@
1
+ import type { NodeId } from "../ids.js";
2
+ import type { JsonObject } from "../json.js";
3
+ import type { LoomNode } from "../tree/node.js";
4
+ import type { LoomTree } from "../tree/tree.js";
5
+ import { type BindingError } from "./binding.js";
6
+ import type { BindingName, SourceId } from "./source.js";
7
+ /**
8
+ * What a tree wants to know, worked out before anything is asked.
9
+ *
10
+ * Planning is a pure function of the tree, which is the whole reason the seam is
11
+ * shaped this way. `renderLoomTree` is synchronous and does no IO — that is what
12
+ * lets it run inside a Server Component and what makes two renders of one
13
+ * revision agree — and resolving a binding is IO by definition. So the tree is
14
+ * read once, in a pass that only reads, and the asking happens outside the
15
+ * renderer entirely (0058).
16
+ *
17
+ * Identical questions are asked once. Hermes' `about` block bound three fields
18
+ * to one profile, and three round trips for one row is a cost paid on every
19
+ * request forever; two bindings naming the same source with the same params
20
+ * share a key here and therefore share an answer.
21
+ */
22
+ /** Identifies one question. Two bindings sharing it share an answer. */
23
+ export type RequestKey = string;
24
+ export type PlannedRequest = {
25
+ readonly key: RequestKey;
26
+ readonly source: SourceId;
27
+ readonly params: JsonObject;
28
+ };
29
+ export type PlannedBinding = {
30
+ readonly nodeId: NodeId;
31
+ readonly name: BindingName;
32
+ readonly key: RequestKey;
33
+ };
34
+ /** A node whose `loom:data` could not be read at all. */
35
+ export type BindingProblem = {
36
+ readonly nodeId: NodeId;
37
+ readonly error: BindingError;
38
+ };
39
+ export type DataPlan = {
40
+ /** Deduplicated, in first-encountered order. */
41
+ readonly requests: readonly PlannedRequest[];
42
+ readonly bindings: readonly PlannedBinding[];
43
+ readonly problems: readonly BindingProblem[];
44
+ };
45
+ export declare const EMPTY_DATA_PLAN: DataPlan;
46
+ export declare const planIsEmpty: (plan: DataPlan) => boolean;
47
+ export declare const planTreeData: (tree: LoomTree) => DataPlan;
48
+ /**
49
+ * The same plan, for a root that is not a stored tree.
50
+ *
51
+ * Exactly the split `planSubmissionsIn` carries next door, for the reason its
52
+ * comment gives: the runtime needs a plan for a tree that exists only as the
53
+ * result of applying a delta, which is a node and never a `LoomTree`. Reading
54
+ * the bindings twice would be two walks that had to agree about which
55
+ * declarations parse, and the second one would drift.
56
+ */
57
+ export declare const planDataIn: (root: LoomNode) => DataPlan;
58
+ //# sourceMappingURL=plan.d.ts.map
Binary file
@@ -0,0 +1,91 @@
1
+ import type { NodeId } from "../ids.js";
2
+ import type { JsonValue } from "../json.js";
3
+ import type { Result } from "../result.js";
4
+ import type { BindingError } from "./binding.js";
5
+ import type { DataUnavailable } from "./adapter.js";
6
+ import type { DataPlan, RequestKey } from "./plan.js";
7
+ import type { BindingName, SourceId } from "./source.js";
8
+ /**
9
+ * The answers, indexed the way a render walk needs them.
10
+ *
11
+ * Nothing here knows about React, and that is deliberate: the seam is asking a
12
+ * host questions about its own data, which is not a rendering concern. The
13
+ * renderer depends on this module; this module depends on nothing above it, so a
14
+ * host can plan and resolve a tree's data without loading the renderer at all.
15
+ */
16
+ /**
17
+ * A binding either has an answer or has a named reason it does not. There is no
18
+ * third state, and in particular there is no way to express "empty" as a failure
19
+ * — a source that legitimately answers with nothing answers `ready` with an
20
+ * empty list. Collapsing the two is the mistake the portal spent a run undoing:
21
+ * a reader who takes "we could not reach your services" for "you have no
22
+ * services" concludes their data is gone.
23
+ */
24
+ export type DataOutcome = {
25
+ readonly status: "ready";
26
+ readonly value: JsonValue;
27
+ } | {
28
+ readonly status: "unavailable";
29
+ readonly unavailable: DataUnavailable;
30
+ };
31
+ /**
32
+ * One node's answers, by binding name. Null-prototype for the reason
33
+ * `staticPrimitiveResolver` gives: binding names are identifiers and
34
+ * `constructor` and `valueOf` are valid ones, so a plain object would answer
35
+ * `loom.data.constructor` with a function off `Object.prototype`.
36
+ */
37
+ export type NodeData = Readonly<Record<string, DataOutcome>>;
38
+ export declare const NO_DATA: NodeData;
39
+ /**
40
+ * One node's answers, built from a plain record.
41
+ *
42
+ * `buildDataResolution` is the only thing in the runtime that produces a
43
+ * `NodeData` from a plan, and everything else that needs one — a probe handed
44
+ * answers, a test, a fixture — was writing `Object.create(null)` and a loop.
45
+ * The null prototype is the whole reason this is not an object literal, and it
46
+ * is the kind of detail every caller gets right once and then forgets.
47
+ */
48
+ export declare const nodeDataOf: (answers: Readonly<Record<string, DataOutcome>>) => NodeData;
49
+ /** What a node's data could not do, in the seam's own vocabulary. */
50
+ export type NodeDataProblem = {
51
+ readonly kind: "misdeclared";
52
+ readonly error: BindingError;
53
+ } | {
54
+ readonly kind: "unavailable";
55
+ readonly name: BindingName;
56
+ readonly source: SourceId;
57
+ readonly unavailable: DataUnavailable;
58
+ };
59
+ export interface DataResolution {
60
+ /**
61
+ * Always answers. `NO_DATA` means *this node asked for nothing* — it is not a
62
+ * way to say "I have no answers for you", and an implementation that uses it as
63
+ * one is reporting an absence as a satisfied request.
64
+ *
65
+ * The render walk holds a resolution to that: a node that declares bindings and
66
+ * gets `NO_DATA` with no problems beside it earns a `data-unresolved`
67
+ * diagnostic, because the only way to be in that state honestly is to have been
68
+ * built from a different tree's plan.
69
+ */
70
+ readonly lookup: (nodeId: NodeId) => NodeData;
71
+ readonly problemsFor: (nodeId: NodeId) => readonly NodeDataProblem[];
72
+ }
73
+ /**
74
+ * The resolution of a plan that asks nothing, which is the only tree it is
75
+ * correct for.
76
+ *
77
+ * It exists so `resolveDataPlan` can short-circuit an empty plan, and its name
78
+ * makes it the obvious thing to reach for when writing a composition root that
79
+ * has no data — which is the one use it does not serve. Handed a tree whose nodes
80
+ * do bind, it answers `NO_DATA` for all of them, and every one of those bindings
81
+ * is reported `unresolved` by the walk rather than disappearing.
82
+ */
83
+ export declare const EMPTY_DATA_RESOLUTION: DataResolution;
84
+ /**
85
+ * Folds a plan and its answers into the two lookups the walk uses. Separated
86
+ * from `resolveDataPlan` because it is pure: given the same answers it builds
87
+ * the same resolution, which is what makes the failure paths testable without a
88
+ * fake adapter for each one.
89
+ */
90
+ export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, Result<JsonValue, DataUnavailable>>) => DataResolution;
91
+ //# sourceMappingURL=resolution.d.ts.map
@@ -0,0 +1,96 @@
1
+ export const NO_DATA = Object.freeze(Object.create(null));
2
+ /**
3
+ * One node's answers, built from a plain record.
4
+ *
5
+ * `buildDataResolution` is the only thing in the runtime that produces a
6
+ * `NodeData` from a plan, and everything else that needs one — a probe handed
7
+ * answers, a test, a fixture — was writing `Object.create(null)` and a loop.
8
+ * The null prototype is the whole reason this is not an object literal, and it
9
+ * is the kind of detail every caller gets right once and then forgets.
10
+ */
11
+ export const nodeDataOf = (answers) => {
12
+ const bag = Object.create(null);
13
+ for (const name of Object.keys(answers)) {
14
+ const outcome = answers[name];
15
+ if (outcome)
16
+ bag[name] = outcome;
17
+ }
18
+ return Object.freeze(bag);
19
+ };
20
+ const NO_PROBLEMS = Object.freeze([]);
21
+ /**
22
+ * The resolution of a plan that asks nothing, which is the only tree it is
23
+ * correct for.
24
+ *
25
+ * It exists so `resolveDataPlan` can short-circuit an empty plan, and its name
26
+ * makes it the obvious thing to reach for when writing a composition root that
27
+ * has no data — which is the one use it does not serve. Handed a tree whose nodes
28
+ * do bind, it answers `NO_DATA` for all of them, and every one of those bindings
29
+ * is reported `unresolved` by the walk rather than disappearing.
30
+ */
31
+ export const EMPTY_DATA_RESOLUTION = {
32
+ lookup: () => NO_DATA,
33
+ problemsFor: () => NO_PROBLEMS,
34
+ };
35
+ /**
36
+ * Folds a plan and its answers into the two lookups the walk uses. Separated
37
+ * from `resolveDataPlan` because it is pure: given the same answers it builds
38
+ * the same resolution, which is what makes the failure paths testable without a
39
+ * fake adapter for each one.
40
+ */
41
+ export const buildDataResolution = (plan, answers) => {
42
+ const data = new Map();
43
+ const problems = new Map();
44
+ const problemsOn = (nodeId) => {
45
+ const existing = problems.get(nodeId);
46
+ if (existing)
47
+ return existing;
48
+ const created = [];
49
+ problems.set(nodeId, created);
50
+ return created;
51
+ };
52
+ for (const problem of plan.problems) {
53
+ problemsOn(problem.nodeId).push({ kind: "misdeclared", error: problem.error });
54
+ }
55
+ const sourceOf = new Map(plan.requests.map((request) => [request.key, request.source]));
56
+ for (const binding of plan.bindings) {
57
+ const answer = answers.get(binding.key);
58
+ /**
59
+ * A planned binding with no answer is a caller that resolved a different
60
+ * plan than the one it is rendering. Reported as unavailable rather than
61
+ * ignored: a page silently missing the data it asked for is the failure
62
+ * mode this whole module is arranged to prevent.
63
+ */
64
+ const outcome = !answer
65
+ ? {
66
+ status: "unavailable",
67
+ unavailable: {
68
+ reason: "not-resolved",
69
+ detail: "the answers came from resolving a different plan than this tree",
70
+ },
71
+ }
72
+ : answer.ok
73
+ ? { status: "ready", value: answer.value }
74
+ : { status: "unavailable", unavailable: answer.error };
75
+ const existing = data.get(binding.nodeId);
76
+ const bag = existing ?? Object.create(null);
77
+ if (!existing)
78
+ data.set(binding.nodeId, bag);
79
+ bag[binding.name] = outcome;
80
+ if (outcome.status === "unavailable") {
81
+ problemsOn(binding.nodeId).push({
82
+ kind: "unavailable",
83
+ name: binding.name,
84
+ source: sourceOf.get(binding.key) ?? binding.key,
85
+ unavailable: outcome.unavailable,
86
+ });
87
+ }
88
+ }
89
+ for (const bag of data.values())
90
+ Object.freeze(bag);
91
+ return {
92
+ lookup: (nodeId) => data.get(nodeId) ?? NO_DATA,
93
+ problemsFor: (nodeId) => problems.get(nodeId) ?? NO_PROBLEMS,
94
+ };
95
+ };
96
+ //# sourceMappingURL=resolution.js.map
@@ -0,0 +1,46 @@
1
+ import type { JsonObject } from "../json.js";
2
+ import type { LoomTree } from "../tree/tree.js";
3
+ import type { DataRegistry } from "./adapter.js";
4
+ import { type DataPlan } from "./plan.js";
5
+ import { type DataResolution } from "./resolution.js";
6
+ /**
7
+ * The one step in serving a page that does IO.
8
+ *
9
+ * Every question in the plan is asked at once. They are independent by
10
+ * construction — a plan is a set of source-and-params pairs with no ordering
11
+ * between them — so asking them in sequence would make a page's latency the sum
12
+ * of its integrations rather than the slowest of them. Nothing here rejects:
13
+ * each entry's failure is captured against its own key, so one integration
14
+ * having a bad afternoon costs one region of the page rather than the page.
15
+ *
16
+ * That last sentence was not true until 13 September, and it is the reason for
17
+ * the ceiling (0140). `Promise.all` over a set of independent questions makes the
18
+ * page's latency the slowest of them — including the one that is never going to
19
+ * answer, which is not a latency at all. An adapter that hangs held the whole
20
+ * page, not its own region, and no diagnostic was ever produced for it because
21
+ * nothing had decided it had waited long enough.
22
+ */
23
+ export type ResolveDataOptions = {
24
+ readonly registry: DataRegistry;
25
+ /** Passed through to every adapter — the render request's host context. */
26
+ readonly context?: JsonObject;
27
+ /**
28
+ * How long any one source is given, each independently of the others. Defaults
29
+ * to `DEFAULT_SOURCE_CEILING_MS`; there is no way to wait forever (0140).
30
+ */
31
+ readonly ceilingMs?: number;
32
+ };
33
+ /**
34
+ * Ten seconds per source, which is already several times longer than a reader
35
+ * will wait for a page and generous for a query somebody has indexed.
36
+ *
37
+ * It is per-source rather than per-page because the questions are independent:
38
+ * a page holding one slow integration and five quick ones should show five
39
+ * regions and a diagnostic, not lose a region to whichever source was measured
40
+ * against a budget the others had already spent.
41
+ */
42
+ export declare const DEFAULT_SOURCE_CEILING_MS = 10000;
43
+ export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<DataResolution>;
44
+ /** Plan and resolve in one step, for the ordinary caller that does both. */
45
+ export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<DataResolution>;
46
+ //# sourceMappingURL=resolve.d.ts.map
@@ -0,0 +1,37 @@
1
+ import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
2
+ import { err } from "../result.js";
3
+ import { planTreeData, planIsEmpty } from "./plan.js";
4
+ import { buildDataResolution, EMPTY_DATA_RESOLUTION, } from "./resolution.js";
5
+ /**
6
+ * Ten seconds per source, which is already several times longer than a reader
7
+ * will wait for a page and generous for a query somebody has indexed.
8
+ *
9
+ * It is per-source rather than per-page because the questions are independent:
10
+ * a page holding one slow integration and five quick ones should show five
11
+ * regions and a diagnostic, not lose a region to whichever source was measured
12
+ * against a budget the others had already spent.
13
+ */
14
+ export const DEFAULT_SOURCE_CEILING_MS = 10_000;
15
+ const askOne = async (source, params, options) => {
16
+ const registered = options.registry.source(source);
17
+ if (!registered) {
18
+ return err({
19
+ reason: "no-such-source",
20
+ detail: `registered: ${options.registry.sources.map((entry) => entry.id).join(", ") || "none"}`,
21
+ });
22
+ }
23
+ const ceiling = ceilingOf(options.ceilingMs, DEFAULT_SOURCE_CEILING_MS);
24
+ return withCeiling(ceiling, () => err({ reason: "unavailable", detail: `no answer in ${describeCeiling(ceiling)}` }), (signal) => registered.answer(params, options.context, signal));
25
+ };
26
+ export const resolveDataPlan = async (plan, options) => {
27
+ if (planIsEmpty(plan))
28
+ return EMPTY_DATA_RESOLUTION;
29
+ const answered = await Promise.all(plan.requests.map(async (request) => [
30
+ request.key,
31
+ await askOne(request.source, request.params, options),
32
+ ]));
33
+ return buildDataResolution(plan, new Map(answered));
34
+ };
35
+ /** Plan and resolve in one step, for the ordinary caller that does both. */
36
+ export const resolveTreeData = async (tree, options) => resolveDataPlan(planTreeData(tree), options);
37
+ //# sourceMappingURL=resolve.js.map
@@ -0,0 +1,40 @@
1
+ import { z } from "zod";
2
+ /**
3
+ * What a data source is, from the tree's side of the seam.
4
+ *
5
+ * A binding names a source and says nothing about where the answer comes from.
6
+ * This module holds that name and the shape of the answer, so a tree can ask a
7
+ * question no part of it knows how to answer.
8
+ */
9
+ /**
10
+ * The grammar a source id has to satisfy, in words, said once.
11
+ *
12
+ * The same sentence reaches two very different readers. `describeDataRegistryError`
13
+ * tells a host that registered a bad id, and that reader has the code open. A
14
+ * misdeclared `loom:data` in a tree reaches somebody looking at a page that will
15
+ * not bind, through a render diagnostic — and Zod's default for a failed
16
+ * `.regex()` is the word `Invalid`, so the less informed reader was getting the
17
+ * less useful message. One constant rather than two strings, because the two
18
+ * drifting apart is the same defect wearing a different hat.
19
+ */
20
+ export declare const SOURCE_ID_EXPECTATION = "expected dot-namespaced kebab-case, like \"commerce.products\"";
21
+ /**
22
+ * The identifier of a registered data source — the contract between a binding
23
+ * in the tree and whatever answers it.
24
+ *
25
+ * Same grammar as `PrimitiveType`, and for the same reason: a tree names a
26
+ * capability, a registry decides what that name reaches, and the AST stays
27
+ * independent of any particular host's data. `profile`, `commerce.products`.
28
+ */
29
+ export declare const sourceIdSchema: z.ZodBranded<z.ZodString, "SourceId">;
30
+ export type SourceId = z.infer<typeof sourceIdSchema>;
31
+ /** The grammar a binding name has to satisfy, for the same reader. */
32
+ export declare const BINDING_NAME_EXPECTATION = "expected camelCase, like \"services\"";
33
+ /**
34
+ * The name a primitive reads an answer under — `loom.data.services`. camelCase,
35
+ * mirroring slot names and prop names, because it is the same kind of thing: a
36
+ * named region of what a primitive receives.
37
+ */
38
+ export declare const bindingNameSchema: z.ZodBranded<z.ZodString, "BindingName">;
39
+ export type BindingName = z.infer<typeof bindingNameSchema>;
40
+ //# sourceMappingURL=source.d.ts.map
@@ -0,0 +1,45 @@
1
+ import { z } from "zod";
2
+ import { NAMESPACED_ID_PATTERN } from "../primitive-type.js";
3
+ /**
4
+ * What a data source is, from the tree's side of the seam.
5
+ *
6
+ * A binding names a source and says nothing about where the answer comes from.
7
+ * This module holds that name and the shape of the answer, so a tree can ask a
8
+ * question no part of it knows how to answer.
9
+ */
10
+ /**
11
+ * The grammar a source id has to satisfy, in words, said once.
12
+ *
13
+ * The same sentence reaches two very different readers. `describeDataRegistryError`
14
+ * tells a host that registered a bad id, and that reader has the code open. A
15
+ * misdeclared `loom:data` in a tree reaches somebody looking at a page that will
16
+ * not bind, through a render diagnostic — and Zod's default for a failed
17
+ * `.regex()` is the word `Invalid`, so the less informed reader was getting the
18
+ * less useful message. One constant rather than two strings, because the two
19
+ * drifting apart is the same defect wearing a different hat.
20
+ */
21
+ export const SOURCE_ID_EXPECTATION = 'expected dot-namespaced kebab-case, like "commerce.products"';
22
+ /**
23
+ * The identifier of a registered data source — the contract between a binding
24
+ * in the tree and whatever answers it.
25
+ *
26
+ * Same grammar as `PrimitiveType`, and for the same reason: a tree names a
27
+ * capability, a registry decides what that name reaches, and the AST stays
28
+ * independent of any particular host's data. `profile`, `commerce.products`.
29
+ */
30
+ export const sourceIdSchema = z
31
+ .string()
32
+ .regex(NAMESPACED_ID_PATTERN, SOURCE_ID_EXPECTATION)
33
+ .brand();
34
+ /** The grammar a binding name has to satisfy, for the same reader. */
35
+ export const BINDING_NAME_EXPECTATION = 'expected camelCase, like "services"';
36
+ /**
37
+ * The name a primitive reads an answer under — `loom.data.services`. camelCase,
38
+ * mirroring slot names and prop names, because it is the same kind of thing: a
39
+ * named region of what a primitive receives.
40
+ */
41
+ export const bindingNameSchema = z
42
+ .string()
43
+ .regex(/^[a-z][a-zA-Z0-9]*$/, BINDING_NAME_EXPECTATION)
44
+ .brand();
45
+ //# sourceMappingURL=source.js.map
@@ -0,0 +1,57 @@
1
+ /**
2
+ * A ceiling on an await into somebody else's code.
3
+ *
4
+ * Loom does two things it cannot predict the duration of: it asks a model what
5
+ * to change, and it asks a host's adapter to answer a binding. Both are
6
+ * documented as *reportable* failures — `ModelClientError.unavailable` is "the
7
+ * service could not answer now" and `SourceFailure.unavailable` says in as many
8
+ * words that it covers "a timeout, a dead connection" — and neither seam could
9
+ * produce one, because nothing in the runtime ever stopped waiting.
10
+ *
11
+ * A call that never answers is the worst of the failure modes and the only one
12
+ * with no sentence: a surface shows a spinner, the log says nothing, and the
13
+ * thing that eventually gives up is the reader. Sandboxed deployments make it
14
+ * routine rather than exotic — Node's `fetch` ignores `HTTPS_PROXY`, so a
15
+ * request behind a proxy is not refused, it is simply never answered.
16
+ *
17
+ * So: **the runtime, not the host, decides how long it is prepared to wait**, and
18
+ * an expiry is an ordinary value in the vocabulary the seam already has. There is
19
+ * deliberately no way to switch a ceiling off. A caller that wants to wait twenty
20
+ * minutes names twenty minutes, which is a number a reader of the call site can
21
+ * see; `undefined` meaning "forever" is not.
22
+ */
23
+ /**
24
+ * The ceiling a caller named, or the default when it named nothing usable.
25
+ *
26
+ * `clampLimit`'s rule, for the same reason: this value reaches a `setTimeout`,
27
+ * where a `NaN` fires immediately and a negative one fires immediately, and
28
+ * both of those turn a slow page into an instantly broken one.
29
+ */
30
+ export declare const ceilingOf: (given: number | undefined, fallback: number) => number;
31
+ /** `250ms`, `10s`, `3m` — a ceiling in the unit somebody would say it in. */
32
+ export declare const describeCeiling: (ms: number) => string;
33
+ /**
34
+ * Runs `attempt` with a ceiling, and answers with `expired()` if it is reached
35
+ * first.
36
+ *
37
+ * The signal is the half that matters as much as the answer. Walking away from a
38
+ * promise does not stop the work behind it: without the abort, a page that gave
39
+ * up on an integration still holds its socket, and under load the connections a
40
+ * deployment leaks are the ones it already stopped waiting for. An
41
+ * implementation that ignores the signal still cannot delay the answer — it can
42
+ * only fail to release what it is holding.
43
+ *
44
+ * This never rejects for a reason `attempt` did not give it, and a rejection
45
+ * arriving after the race is decided never reaches Node as an unhandled one —
46
+ * which would take a server down for a call the runtime had already reported on.
47
+ *
48
+ * Most of that second half is `Promise.race`'s, not this module's: `race`
49
+ * subscribes to every promise it is handed, synchronously, so the loser already
50
+ * has a reaction attached by the time it settles. The explicit `catch` below
51
+ * therefore changes nothing about how this code behaves today, and `deadline.test.ts`
52
+ * says so where it would otherwise read as the test of a mechanism it cannot see.
53
+ * The line stays because the property is worth keeping true under an edit that
54
+ * replaces the race with a hand-rolled resolver, where it stops being free.
55
+ */
56
+ export declare const withCeiling: <T>(ceilingMs: number, expired: () => T, attempt: (signal: AbortSignal) => Promise<T>) => Promise<T>;
57
+ //# sourceMappingURL=deadline.d.ts.map
@@ -0,0 +1,78 @@
1
+ /**
2
+ * A ceiling on an await into somebody else's code.
3
+ *
4
+ * Loom does two things it cannot predict the duration of: it asks a model what
5
+ * to change, and it asks a host's adapter to answer a binding. Both are
6
+ * documented as *reportable* failures — `ModelClientError.unavailable` is "the
7
+ * service could not answer now" and `SourceFailure.unavailable` says in as many
8
+ * words that it covers "a timeout, a dead connection" — and neither seam could
9
+ * produce one, because nothing in the runtime ever stopped waiting.
10
+ *
11
+ * A call that never answers is the worst of the failure modes and the only one
12
+ * with no sentence: a surface shows a spinner, the log says nothing, and the
13
+ * thing that eventually gives up is the reader. Sandboxed deployments make it
14
+ * routine rather than exotic — Node's `fetch` ignores `HTTPS_PROXY`, so a
15
+ * request behind a proxy is not refused, it is simply never answered.
16
+ *
17
+ * So: **the runtime, not the host, decides how long it is prepared to wait**, and
18
+ * an expiry is an ordinary value in the vocabulary the seam already has. There is
19
+ * deliberately no way to switch a ceiling off. A caller that wants to wait twenty
20
+ * minutes names twenty minutes, which is a number a reader of the call site can
21
+ * see; `undefined` meaning "forever" is not.
22
+ */
23
+ /**
24
+ * The ceiling a caller named, or the default when it named nothing usable.
25
+ *
26
+ * `clampLimit`'s rule, for the same reason: this value reaches a `setTimeout`,
27
+ * where a `NaN` fires immediately and a negative one fires immediately, and
28
+ * both of those turn a slow page into an instantly broken one.
29
+ */
30
+ export const ceilingOf = (given, fallback) => given !== undefined && Number.isFinite(given) && given > 0 ? given : fallback;
31
+ /** `250ms`, `10s`, `3m` — a ceiling in the unit somebody would say it in. */
32
+ export const describeCeiling = (ms) => {
33
+ if (ms >= 60_000 && ms % 60_000 === 0)
34
+ return `${ms / 60_000}m`;
35
+ if (ms >= 1_000)
36
+ return `${Number((ms / 1_000).toFixed(2))}s`;
37
+ return `${ms}ms`;
38
+ };
39
+ /**
40
+ * Runs `attempt` with a ceiling, and answers with `expired()` if it is reached
41
+ * first.
42
+ *
43
+ * The signal is the half that matters as much as the answer. Walking away from a
44
+ * promise does not stop the work behind it: without the abort, a page that gave
45
+ * up on an integration still holds its socket, and under load the connections a
46
+ * deployment leaks are the ones it already stopped waiting for. An
47
+ * implementation that ignores the signal still cannot delay the answer — it can
48
+ * only fail to release what it is holding.
49
+ *
50
+ * This never rejects for a reason `attempt` did not give it, and a rejection
51
+ * arriving after the race is decided never reaches Node as an unhandled one —
52
+ * which would take a server down for a call the runtime had already reported on.
53
+ *
54
+ * Most of that second half is `Promise.race`'s, not this module's: `race`
55
+ * subscribes to every promise it is handed, synchronously, so the loser already
56
+ * has a reaction attached by the time it settles. The explicit `catch` below
57
+ * therefore changes nothing about how this code behaves today, and `deadline.test.ts`
58
+ * says so where it would otherwise read as the test of a mechanism it cannot see.
59
+ * The line stays because the property is worth keeping true under an edit that
60
+ * replaces the race with a hand-rolled resolver, where it stops being free.
61
+ */
62
+ export const withCeiling = (ceilingMs, expired, attempt) => {
63
+ const controller = new AbortController();
64
+ let timer;
65
+ const reached = new Promise((resolve) => {
66
+ timer = setTimeout(() => {
67
+ controller.abort(new Error(`no answer in ${describeCeiling(ceilingMs)}`));
68
+ resolve(expired());
69
+ }, ceilingMs);
70
+ });
71
+ const answered = attempt(controller.signal);
72
+ /** Belt to `race`'s braces, and the module comment says which is load-bearing. */
73
+ answered.catch(() => undefined);
74
+ return Promise.race([answered, reached]).finally(() => {
75
+ clearTimeout(timer);
76
+ });
77
+ };
78
+ //# sourceMappingURL=deadline.js.map
@@ -0,0 +1,24 @@
1
+ import type { FrameOrigin, FrameOriginRegistry } from "./origin.js";
2
+ /**
3
+ * Whose documents this deployment will frame, as a model is told it.
4
+ *
5
+ * The same projection `submissionCatalogue` makes for endpoints, and it exists
6
+ * for the same reason turned around. An endpoint catalogue lists the *only*
7
+ * things a model may name, because an address never appears in a tree. A frame
8
+ * URL does appear in a tree — a model picks which video — so this catalogue is
9
+ * not the whole of what may be written. It is the difference between a model
10
+ * proposing a video that renders and a model proposing one that renders a
11
+ * refusal, which is the difference between a good page and a wasted turn.
12
+ *
13
+ * `self` is deliberately not projected. Whether an origin is the deployment's
14
+ * own changes what a frame is worth to whoever runs the deployment, and nothing
15
+ * at all about which video belongs on the page.
16
+ */
17
+ export type CataloguedFrameOrigin = {
18
+ readonly origin: FrameOrigin;
19
+ /** One line, written by whoever runs the deployment. */
20
+ readonly description: string;
21
+ };
22
+ export type FrameCatalogue = readonly CataloguedFrameOrigin[];
23
+ export declare const frameCatalogue: (registry: FrameOriginRegistry) => FrameCatalogue;
24
+ //# sourceMappingURL=catalogue.d.ts.map
@@ -0,0 +1,5 @@
1
+ export const frameCatalogue = (registry) => registry.origins.map((origin) => ({
2
+ origin: origin.origin,
3
+ description: origin.description,
4
+ }));
5
+ //# sourceMappingURL=catalogue.js.map