@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,231 @@
1
+ import type { ProposalId, TreeId } from "../ids.js";
2
+ import { type PageDirection, type PageEnds } from "../paging.js";
3
+ import type { TreeDelta } from "../tree/delta.js";
4
+ import type { LoomTree } from "../tree/tree.js";
5
+ import type { Provenance } from "../runtime/proposal.js";
6
+ import type { Result } from "../result.js";
7
+ import type { StoreError } from "./errors.js";
8
+ /**
9
+ * Persistence: an append-only log of accepted deltas, and the current tree as a
10
+ * materialised view of it.
11
+ *
12
+ * The log is the truth. Every entry is a delta with the provenance that produced
13
+ * it, which is what makes 0001's claim real rather than aspirational — a stored
14
+ * tree can say what it is, but only a log can say who changed it, when, and why.
15
+ * §6 reads the same entries.
16
+ *
17
+ * The snapshot exists because §3 renders per request on an edge runtime. A pure
18
+ * log would make every render a fold over the whole history, and no cache
19
+ * invalidation fixes that, because the fold *is* the read. It also insures
20
+ * against a subtler problem: a log is a recipe, and replaying it correctly
21
+ * forever requires `applyDelta` to stay bit-stable forever. §1's `move`
22
+ * convention is baked into every stored delta. With a snapshot, replay is only
23
+ * ever needed for audit — see `auditSnapshot`, which is what turns drift from a
24
+ * silent rewrite of history into a test failure.
25
+ */
26
+ export type StoredRevision = {
27
+ readonly treeId: TreeId;
28
+ /** The revision this entry produced, so `revision - 1` is what it applied to. */
29
+ readonly revision: number;
30
+ readonly proposalId: ProposalId;
31
+ readonly delta: TreeDelta;
32
+ readonly provenance: Provenance;
33
+ /** When the runtime applied it, which is not when the model produced it. */
34
+ readonly appliedAt: string;
35
+ /**
36
+ * Who allowed it, when a human had to (0029).
37
+ *
38
+ * Distinct from `provenance.actor`, which is who *asked*. A hold exists to put
39
+ * a second person in the way of a change, so recording only the asker would
40
+ * make every confirmed change look like somebody waving through their own
41
+ * request.
42
+ *
43
+ * Absent on a change nobody had to allow — one the Gate accepted outright —
44
+ * and absent on everything written before the column existed (0029), which nobody can prove the
45
+ * approver of. It is never back-filled: the log is append-only (0016), and a
46
+ * fact nobody observed does not belong in it.
47
+ */
48
+ readonly answeredBy?: string;
49
+ };
50
+ export type AppendRequest = {
51
+ readonly proposalId: ProposalId;
52
+ readonly delta: TreeDelta;
53
+ readonly provenance: Provenance;
54
+ readonly appliedAt: string;
55
+ /** Set only by the confirmation path; see `StoredRevision.answeredBy`. */
56
+ readonly answeredBy?: string;
57
+ };
58
+ /**
59
+ * What a listing says about a tree without loading it.
60
+ *
61
+ * `revision` is the whole summary, and it is enough: it starts at 0 and
62
+ * increments once per accepted delta, so it is also the number of entries in the
63
+ * log. There is no timestamp because a `LoomTree` carries none — §1 kept time out
64
+ * of the document deliberately, and a listing that invented one would be a field
65
+ * only some implementations could fill honestly.
66
+ */
67
+ export type TreeListing = {
68
+ readonly treeId: TreeId;
69
+ readonly revision: number;
70
+ };
71
+ export type ListRequest = {
72
+ /**
73
+ * Opaque to the caller: the previous page's `cursor`, passed back unread.
74
+ * Absent starts at the beginning. A cursor naming a tree that has since been
75
+ * removed is not an error — listing resumes from the next key after it.
76
+ */
77
+ readonly cursor?: string;
78
+ /** Clamped by the implementation — see `clampListingLimit`. */
79
+ readonly limit?: number;
80
+ };
81
+ export type TreeListPage = {
82
+ readonly trees: readonly TreeListing[];
83
+ /** `null` when this was the last page. */
84
+ readonly cursor: string | null;
85
+ };
86
+ /**
87
+ * How a log is read: a page taken from one end of it, never the whole thing.
88
+ *
89
+ * A revision log grows once per accepted delta and is never compacted, so a read
90
+ * that returns all of it costs more the longer a tree has been edited — fastest
91
+ * exactly when the log is most worth reading. 0025 settled this shape for the
92
+ * telemetry journal; a revision log is the same kind of sequence and reads the
93
+ * same way, so the vocabulary is shared rather than reinvented.
94
+ */
95
+ /**
96
+ * Where a read begins. Two kinds of position, and they are not interchangeable.
97
+ *
98
+ * A `cursor` is the store's word: opaque, exclusive, and only meaningful because
99
+ * a page handed it back. An `at` is the caller's word: a revision number, which
100
+ * is public, stable, and already the entry's identity — so a caller holding one
101
+ * can name it without having read the page it falls on.
102
+ *
103
+ * They are mutually exclusive in the type rather than by convention, because the
104
+ * only alternative is a precedence rule, and a request that quietly ignores half
105
+ * of what it was asked is the failure mode this contract avoids everywhere else.
106
+ */
107
+ export type RevisionStart = {
108
+ /** A cursor from a previous page's `older`/`newer`, passed back unread. */
109
+ readonly cursor?: string;
110
+ readonly at?: never;
111
+ } | {
112
+ /**
113
+ * A revision to open at. **Inclusive** — the page contains it — which is
114
+ * the difference that matters: a caller naming this has been sent to a
115
+ * change and wants to see it, not to resume beside it.
116
+ *
117
+ * `direction` still says which way the rest of the page runs: `older`
118
+ * puts the named revision at the newest end of the page, `newer` at the
119
+ * oldest. A revision no entry holds is not an error; the page is whatever
120
+ * falls on the named side of it, which may be empty.
121
+ */
122
+ readonly at?: number;
123
+ readonly cursor?: never;
124
+ };
125
+ export type RevisionReadRequest = RevisionStart & {
126
+ /**
127
+ * Default `newer`, which with no cursor is the oldest page — the read a fold
128
+ * wants, and the one `auditSnapshot` takes. `older` with no cursor is the
129
+ * newest page, which is what a reader looking at a tree asks for.
130
+ */
131
+ readonly direction?: PageDirection;
132
+ readonly limit?: number;
133
+ };
134
+ export type RevisionPage = PageEnds & {
135
+ /**
136
+ * Always ascending by `revision`, whichever end the page was taken from.
137
+ *
138
+ * A log is folded by `replayTree` in the order the entries were applied, and a
139
+ * page that sometimes came back reversed would make every consumer responsible
140
+ * for knowing which — and silently wrong when it guessed.
141
+ */
142
+ readonly revisions: readonly StoredRevision[];
143
+ };
144
+ export declare const DEFAULT_LISTING_LIMIT = 50;
145
+ export declare const MAX_LISTING_LIMIT = 200;
146
+ /**
147
+ * Larger than a tree listing's page and smaller than the journal's. A revision
148
+ * carries a whole delta and its provenance, so a page of these is heavier than a
149
+ * page of listings; but unlike telemetry records, one entry is one complete
150
+ * thing to read, so a page never splits something that has to be folded back
151
+ * together.
152
+ */
153
+ export declare const DEFAULT_REVISION_LIMIT = 100;
154
+ export declare const MAX_REVISION_LIMIT = 500;
155
+ export declare const clampRevisionLimit: (limit: number | undefined) => number;
156
+ /**
157
+ * The revision the first log entry produces. A tree is created at revision 0 and
158
+ * nothing in the log corresponds to that, so 1 is the oldest position a read can
159
+ * reach — and revisions are dense from there, one per accepted delta (0026).
160
+ */
161
+ export declare const FIRST_REVISION = 1;
162
+ /**
163
+ * An inclusive revision anchor, as the exclusive bound both implementations
164
+ * already page from.
165
+ *
166
+ * Density is what makes this exact rather than approximate: revisions are
167
+ * consecutive integers, so the position just outside `at` is `at ± 1` and no
168
+ * entry can hide between them. Shared rather than written twice, for the reason
169
+ * `pageEnds` is — it is the part most likely to drift between two backends and
170
+ * least likely to be noticed when it does.
171
+ */
172
+ export declare const anchorBound: (at: number, direction: PageDirection) => number;
173
+ /**
174
+ * Whether an anchored page leaves entries on the side it pages away from — the
175
+ * `resumed` a cursor gets for free and an anchor does not.
176
+ *
177
+ * A cursor came from a page, so entries exist at the position it names and the
178
+ * far side is bounded by definition. An anchor is *inside* the page it produces,
179
+ * so the far side has to be established rather than assumed: paging `older` from
180
+ * revision 5 leaves entries newer than 5 only if the log has gone past it, and
181
+ * paging `newer` leaves entries older only if 5 is not the first.
182
+ *
183
+ * Both answers come from what the store already knows — the head revision it
184
+ * looked up to answer `not-found`, and the density that makes `FIRST_REVISION`
185
+ * the floor — so neither costs a read.
186
+ */
187
+ export declare const anchorResumes: (at: number, direction: PageDirection, headRevision: number) => boolean;
188
+ /**
189
+ * Every implementation clamps the same way, so a caller cannot ask a store for
190
+ * everything it holds by omitting a limit or naming a large one. The rule is
191
+ * shared with every other listing in Loom; only the bounds are this one's.
192
+ */
193
+ export declare const clampListingLimit: (limit: number | undefined) => number;
194
+ /**
195
+ * Three reads and two writes. `head` is the O(1) read §3 needs; `revisions` is
196
+ * the one §6 and the portal's provenance view need; `list` is how a consumer
197
+ * finds a tree it did not create; `append` is the only way a tree ever changes,
198
+ * so nothing can advance a revision without leaving a record of why.
199
+ *
200
+ * Every read is bounded. `head` is one tree, and the other two are pages with a
201
+ * clamped limit — so no caller can ask a store for everything it holds, whether
202
+ * by naming a large limit or by naming none.
203
+ *
204
+ * `list` takes no scope argument because `head` and `revisions` take none
205
+ * either: a store handle *is* the scope it can see. A tenant gets a handle
206
+ * narrowed to its own trees, which is a decision the host makes once when it
207
+ * builds the store rather than one every caller has to remember to pass — and it
208
+ * means listing cannot reach further than reading already could.
209
+ *
210
+ * **Pages are ordered by `treeId`, ascending.** Not by recency, however much a
211
+ * portal would prefer it: ordering has to be total and stable for a cursor to
212
+ * mean anything, and `treeId` is the only key every implementation is guaranteed
213
+ * to have. Recency is a view over data the store does not hold.
214
+ */
215
+ export interface TreeStore {
216
+ readonly create: (tree: LoomTree) => Promise<Result<LoomTree, StoreError>>;
217
+ readonly head: (treeId: TreeId) => Promise<Result<LoomTree, StoreError>>;
218
+ readonly revisions: (treeId: TreeId, request?: RevisionReadRequest) => Promise<Result<RevisionPage, StoreError>>;
219
+ readonly list: (request?: ListRequest) => Promise<Result<TreeListPage, StoreError>>;
220
+ readonly append: (treeId: TreeId, request: AppendRequest) => Promise<Result<LoomTree, StoreError>>;
221
+ }
222
+ /**
223
+ * The read half, for consumers that never write.
224
+ *
225
+ * Depending on the whole store to read from it is what forces a renderer's tree
226
+ * source, or a snapshot audit, to be handed something that can also append. It
227
+ * also makes every stub grow a method the code under test never calls, which is
228
+ * how a test starts describing the interface instead of the behaviour.
229
+ */
230
+ export type TreeReader = Pick<TreeStore, "head" | "revisions">;
231
+ //# sourceMappingURL=store.d.ts.map
@@ -0,0 +1,52 @@
1
+ import { clampLimit } from "../paging.js";
2
+ export const DEFAULT_LISTING_LIMIT = 50;
3
+ export const MAX_LISTING_LIMIT = 200;
4
+ /**
5
+ * Larger than a tree listing's page and smaller than the journal's. A revision
6
+ * carries a whole delta and its provenance, so a page of these is heavier than a
7
+ * page of listings; but unlike telemetry records, one entry is one complete
8
+ * thing to read, so a page never splits something that has to be folded back
9
+ * together.
10
+ */
11
+ export const DEFAULT_REVISION_LIMIT = 100;
12
+ export const MAX_REVISION_LIMIT = 500;
13
+ export const clampRevisionLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_REVISION_LIMIT, max: MAX_REVISION_LIMIT });
14
+ /**
15
+ * The revision the first log entry produces. A tree is created at revision 0 and
16
+ * nothing in the log corresponds to that, so 1 is the oldest position a read can
17
+ * reach — and revisions are dense from there, one per accepted delta (0026).
18
+ */
19
+ export const FIRST_REVISION = 1;
20
+ /**
21
+ * An inclusive revision anchor, as the exclusive bound both implementations
22
+ * already page from.
23
+ *
24
+ * Density is what makes this exact rather than approximate: revisions are
25
+ * consecutive integers, so the position just outside `at` is `at ± 1` and no
26
+ * entry can hide between them. Shared rather than written twice, for the reason
27
+ * `pageEnds` is — it is the part most likely to drift between two backends and
28
+ * least likely to be noticed when it does.
29
+ */
30
+ export const anchorBound = (at, direction) => direction === "older" ? Math.floor(at) + 1 : Math.ceil(at) - 1;
31
+ /**
32
+ * Whether an anchored page leaves entries on the side it pages away from — the
33
+ * `resumed` a cursor gets for free and an anchor does not.
34
+ *
35
+ * A cursor came from a page, so entries exist at the position it names and the
36
+ * far side is bounded by definition. An anchor is *inside* the page it produces,
37
+ * so the far side has to be established rather than assumed: paging `older` from
38
+ * revision 5 leaves entries newer than 5 only if the log has gone past it, and
39
+ * paging `newer` leaves entries older only if 5 is not the first.
40
+ *
41
+ * Both answers come from what the store already knows — the head revision it
42
+ * looked up to answer `not-found`, and the density that makes `FIRST_REVISION`
43
+ * the floor — so neither costs a read.
44
+ */
45
+ export const anchorResumes = (at, direction, headRevision) => (direction === "older" ? at < headRevision : at > FIRST_REVISION);
46
+ /**
47
+ * Every implementation clamps the same way, so a caller cannot ask a store for
48
+ * everything it holds by omitting a limit or naming a large one. The rule is
49
+ * shared with every other listing in Loom; only the bounds are this one's.
50
+ */
51
+ export const clampListingLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_LISTING_LIMIT, max: MAX_LISTING_LIMIT });
52
+ //# sourceMappingURL=store.js.map
@@ -0,0 +1,18 @@
1
+ import type { StoredRevision } from "./store.js";
2
+ /**
3
+ * Which revisions in this stretch of log are put back, and by which entry.
4
+ *
5
+ * The map holds only revisions whose undo still stands, keyed by the revision
6
+ * that was put back. Where more than one standing entry undoes the same
7
+ * revision, the oldest is the one reported: it is the entry that actually put
8
+ * the change back, and the rest re-applied an inverse to a tree that already
9
+ * had it.
10
+ *
11
+ * **Bounded by what it is given.** An undo that lives outside `entries` is not
12
+ * seen, so a page read from the middle of a long log can report a revision as
13
+ * standing that a later page undoes. That is a property of any bounded read
14
+ * (`attributeTree` reports `examinedTo` for the same reason) and the honest
15
+ * reading of an absence here is "not undone within this stretch".
16
+ */
17
+ export declare const undoneRevisions: (entries: readonly StoredRevision[]) => ReadonlyMap<number, StoredRevision>;
18
+ //# sourceMappingURL=undone.d.ts.map
@@ -0,0 +1,89 @@
1
+ /**
2
+ * Which changes in a log have been put back.
3
+ *
4
+ * `Provenance.undoes` makes the link a field, so a surface reading a log it did
5
+ * not write can follow it without parsing the sentence the runtime composed for
6
+ * people. Following it once is not the whole question, though, and the gap
7
+ * between the two is why this is here rather than left to each surface.
8
+ *
9
+ * **An undo is a change, so an undo can be undone.** If revision 5 puts revision
10
+ * 3 back, and revision 7 puts revision 5 back, then 3 is live again — and if 9
11
+ * puts 7 back, 3 is put back once more. Asking `undoes` alone answers "did
12
+ * anything ever undo this", which is a different question from "is this undone
13
+ * now", and the two disagree exactly when a person changed their mind twice. A
14
+ * surface showing a history is asking the second one.
15
+ *
16
+ * So a revision counts as undone only when some entry undoing it **stands** —
17
+ * is not itself undone by an entry that stands. That resolves without recursion:
18
+ * an undo is always appended after what it undoes, so walking newest-first
19
+ * settles every undoer before the entry it acts on.
20
+ *
21
+ * Nothing is read here. This is a fold over entries the caller already has,
22
+ * because the caller — a history screen — has just paged them to draw them, and
23
+ * a second bounded read to answer a question about the page in hand would be the
24
+ * one this module exists to save.
25
+ */
26
+ /**
27
+ * The entries that claim to undo each revision, newest last.
28
+ *
29
+ * A revision can legally have more than one: two undos of the same change is an
30
+ * odd log rather than an impossible one, and reporting only the first would hide
31
+ * the second from a screen that shows what happened.
32
+ */
33
+ const undoersByRevision = (entries) => {
34
+ const undoers = new Map();
35
+ for (const entry of entries) {
36
+ const undone = entry.provenance.undoes;
37
+ if (undone === undefined)
38
+ continue;
39
+ const found = undoers.get(undone);
40
+ if (found)
41
+ found.push(entry);
42
+ else
43
+ undoers.set(undone, [entry]);
44
+ }
45
+ return undoers;
46
+ };
47
+ /**
48
+ * Which revisions in this stretch of log are put back, and by which entry.
49
+ *
50
+ * The map holds only revisions whose undo still stands, keyed by the revision
51
+ * that was put back. Where more than one standing entry undoes the same
52
+ * revision, the oldest is the one reported: it is the entry that actually put
53
+ * the change back, and the rest re-applied an inverse to a tree that already
54
+ * had it.
55
+ *
56
+ * **Bounded by what it is given.** An undo that lives outside `entries` is not
57
+ * seen, so a page read from the middle of a long log can report a revision as
58
+ * standing that a later page undoes. That is a property of any bounded read
59
+ * (`attributeTree` reports `examinedTo` for the same reason) and the honest
60
+ * reading of an absence here is "not undone within this stretch".
61
+ */
62
+ export const undoneRevisions = (entries) => {
63
+ const undoers = undoersByRevision(entries);
64
+ const newestFirst = [...entries].sort((left, right) => right.revision - left.revision);
65
+ /**
66
+ * Whether each entry's own effect is live. Filled newest-first, so every
67
+ * undoer of an entry is already settled when that entry is reached — an undo
68
+ * is appended after what it undoes, always.
69
+ *
70
+ * A log that broke that ordering would leave an undoer unsettled, and an
71
+ * unsettled undoer is read as not standing. That is the conservative answer:
72
+ * it reports a change as live, which is what the tree itself would show.
73
+ */
74
+ const stands = new Map();
75
+ for (const entry of newestFirst) {
76
+ const against = undoers.get(entry.revision) ?? [];
77
+ stands.set(entry.revision, !against.some((undoer) => stands.get(undoer.revision) ?? false));
78
+ }
79
+ const undone = new Map();
80
+ for (const [revision, against] of undoers) {
81
+ const standing = [...against]
82
+ .sort((left, right) => left.revision - right.revision)
83
+ .find((undoer) => stands.get(undoer.revision) ?? false);
84
+ if (standing)
85
+ undone.set(revision, standing);
86
+ }
87
+ return undone;
88
+ };
89
+ //# sourceMappingURL=undone.js.map
@@ -0,0 +1,20 @@
1
+ import type { EndpointId, EndpointRegistry } from "./endpoint.js";
2
+ /**
3
+ * Where a deployment will accept a submission.
4
+ *
5
+ * The same projection `dataCatalogue` makes for sources, and it exists for the
6
+ * same reason: a model asked to put a contact form on a page can only name an
7
+ * endpoint it was told about. It is deliberately thinner than the data
8
+ * catalogue — an id and a line — because there is nothing else a model may
9
+ * supply. Whether the endpoint posts or gets, where it posts to, and what it
10
+ * carries are all resolved after the choice is made and are none of the model's
11
+ * business.
12
+ */
13
+ export type CataloguedEndpoint = {
14
+ readonly id: EndpointId;
15
+ /** One line, written by the endpoint's author, about what it receives. */
16
+ readonly description: string;
17
+ };
18
+ export type SubmissionCatalogue = readonly CataloguedEndpoint[];
19
+ export declare const submissionCatalogue: (registry: EndpointRegistry) => SubmissionCatalogue;
20
+ //# sourceMappingURL=catalogue.d.ts.map
@@ -0,0 +1,5 @@
1
+ export const submissionCatalogue = (registry) => registry.endpoints.map((endpoint) => ({
2
+ id: endpoint.id,
3
+ description: endpoint.description,
4
+ }));
5
+ //# sourceMappingURL=catalogue.js.map
@@ -0,0 +1,39 @@
1
+ import { type Result } from "../result.js";
2
+ import { type EndpointId } from "./endpoint.js";
3
+ /**
4
+ * What a node says about where it posts, as it appears in the tree.
5
+ *
6
+ * ```json
7
+ * "loom:submit": { "to": "contact.enquiry" }
8
+ * ```
9
+ *
10
+ * One key, and deliberately nothing else. A binding carries params because a
11
+ * read genuinely varies — `{ "limit": 6 }` is a different question of the same
12
+ * source — and 0058 accepted the AI-authored surface that comes with it, guarded
13
+ * by a schema the source declares. A write does not vary that way: a deployment
14
+ * with two mailing lists registers two endpoints, which costs one line and makes
15
+ * the allowlist exact. Params here would add an AI-authored channel into the one
16
+ * place a mistake sends a visitor's data somewhere it was not meant to go, and
17
+ * buy nothing that a second registration does not.
18
+ *
19
+ * The object form rather than a bare id string is what leaves room to be wrong
20
+ * about that. `{ "to": … }` can grow a key; `"contact.enquiry"` can only be
21
+ * migrated, and migrating built trees is the cost 0001 arranged the whole delta
22
+ * model to avoid.
23
+ */
24
+ export type Submission = {
25
+ readonly to: EndpointId;
26
+ };
27
+ export type SubmissionError = {
28
+ /** The path of the offending entry, for a diagnostic a person can act on. */
29
+ readonly path: string;
30
+ readonly message: string;
31
+ };
32
+ export declare const describeSubmissionError: (error: SubmissionError) => string;
33
+ /**
34
+ * Parses the value of `loom:submit`. Total, like every other parse of something
35
+ * that came out of storage: a malformed declaration is reported and the node
36
+ * renders with no target, rather than throwing on a page nobody can then see.
37
+ */
38
+ export declare const parseSubmission: (declared: unknown) => Result<Submission, SubmissionError>;
39
+ //# sourceMappingURL=declaration.d.ts.map
@@ -0,0 +1,30 @@
1
+ import { z } from "zod";
2
+ import { err, ok } from "../result.js";
3
+ import { endpointIdSchema } from "./endpoint.js";
4
+ /**
5
+ * Strict, unlike most parses of stored JSON. Zod's default is to strip what it
6
+ * does not know, and stripping is right for a document that may have been
7
+ * written by an older schema. Here it is not: the one thing this seam exists to
8
+ * keep out of a tree is an address, and a declaration carrying `action` should
9
+ * be refused loudly rather than quietly honoured as if the extra key were not
10
+ * there. A key added later is a key this schema will know about.
11
+ */
12
+ const submissionSchema = z.object({ to: endpointIdSchema }).strict();
13
+ export const describeSubmissionError = (error) => `${error.path}: ${error.message}`;
14
+ /**
15
+ * Parses the value of `loom:submit`. Total, like every other parse of something
16
+ * that came out of storage: a malformed declaration is reported and the node
17
+ * renders with no target, rather than throwing on a page nobody can then see.
18
+ */
19
+ export const parseSubmission = (declared) => {
20
+ const parsed = submissionSchema.safeParse(declared);
21
+ if (!parsed.success) {
22
+ const [issue] = parsed.error.issues;
23
+ return err({
24
+ path: issue && issue.path.length > 0 ? issue.path.map(String).join(".") : "loom:submit",
25
+ message: issue?.message ?? "is not an endpoint id under `to`",
26
+ });
27
+ }
28
+ return ok({ to: parsed.data.to });
29
+ };
30
+ //# sourceMappingURL=declaration.js.map
@@ -0,0 +1,131 @@
1
+ import { z } from "zod";
2
+ import type { JsonObject } from "../json.js";
3
+ import { type Result } from "../result.js";
4
+ /**
5
+ * The host's half of the submission seam: where a form's contents go.
6
+ *
7
+ * A data source answers a question the tree asked. An endpoint is the other
8
+ * direction — it is where a *visitor's* data is sent — and that difference is
9
+ * the whole reason this is a separate seam rather than a source that happens to
10
+ * answer with a URL. A read that goes to the wrong place shows the wrong page;
11
+ * a write that goes to the wrong place sends someone's name, email and message
12
+ * to whoever owns that address.
13
+ *
14
+ * So the address is never in the tree. A proposal may name an endpoint the
15
+ * deployment registered and may do nothing else: it cannot compose one, cannot
16
+ * append to one, and cannot pass anything that reaches one. The registry is the
17
+ * allowlist, exactly as it is for sources and for primitives.
18
+ */
19
+ /**
20
+ * The identifier of a registered endpoint — the contract between `loom:submit`
21
+ * in the tree and whatever receives the submission. `contact.enquiry`,
22
+ * `newsletter.subscribe`.
23
+ */
24
+ export declare const endpointIdSchema: z.ZodBranded<z.ZodString, "EndpointId">;
25
+ export type EndpointId = z.infer<typeof endpointIdSchema>;
26
+ /**
27
+ * A hidden input the primitive must render inside the form. A CSRF token is the
28
+ * reason this exists, and it is the reason resolution is allowed to be slow: a
29
+ * token is minted per request, often against a store, and a seam that could not
30
+ * wait for one would push every host into minting it somewhere else and
31
+ * threading it through `context` by hand.
32
+ */
33
+ export type SubmissionField = {
34
+ readonly name: string;
35
+ readonly value: string;
36
+ };
37
+ /**
38
+ * Where a form posts, as the primitive receives it. Every field here is
39
+ * host-authored; none of it is in the tree, and none of it survives into a
40
+ * delta, a revision or a diff.
41
+ */
42
+ export type SubmissionTarget = {
43
+ readonly action: string;
44
+ readonly method: "get" | "post";
45
+ /** Rendered as hidden inputs, in order. Empty for an endpoint needing none. */
46
+ readonly fields: readonly SubmissionField[];
47
+ };
48
+ export declare const submissionTargetSchema: z.ZodType<SubmissionTarget, z.ZodTypeDef, unknown>;
49
+ /** What an endpoint says when it cannot give a target. */
50
+ export type SubmissionFailure = {
51
+ /**
52
+ * `unavailable` is "ask again later" — a token store that is down, a
53
+ * dependency that timed out. `refused` is "not for you" — a form this
54
+ * audience may not submit, an endpoint the deployment turned off. Separate
55
+ * because a primitive shows different things for them, and because only one
56
+ * of the two is worth trying again.
57
+ */
58
+ readonly code: "unavailable" | "refused";
59
+ readonly detail: string;
60
+ };
61
+ export type EndpointRequest = {
62
+ /** The render request's opaque host context — audience, locale, tenant. */
63
+ readonly context: JsonObject | undefined;
64
+ /**
65
+ * Aborted once the render has stopped waiting for this endpoint, which it
66
+ * will (0140). Pass it to whatever does the IO and the connection is let go;
67
+ * ignore it and the page is still answered on time, but the socket is not.
68
+ */
69
+ readonly signal: AbortSignal | undefined;
70
+ };
71
+ export interface SubmissionEndpoint {
72
+ readonly target: (request: EndpointRequest) => Promise<Result<SubmissionTarget, SubmissionFailure>>;
73
+ }
74
+ /**
75
+ * Why a node has no target. Each is something a primitive may be told about and
76
+ * a diagnostic says out loud; none of them is an exception anyone catches.
77
+ */
78
+ export type SubmissionUnavailable = {
79
+ readonly reason: "no-such-endpoint" | "invalid-target" | "endpoint-threw" | SubmissionFailure["code"];
80
+ readonly detail: string;
81
+ };
82
+ export declare const describeSubmissionUnavailable: (unavailable: SubmissionUnavailable) => string;
83
+ export type EndpointDefinition = {
84
+ readonly id: string;
85
+ /**
86
+ * One line, for the catalogue. A model choosing where a form posts has this
87
+ * and the id to go on, and nothing else — which is the point.
88
+ */
89
+ readonly description: string;
90
+ readonly endpoint: SubmissionEndpoint;
91
+ };
92
+ /**
93
+ * A definition with the host's own types erased, which is what a heterogeneous
94
+ * registry can hold. `defineEndpoint` is the only way to build one, so the
95
+ * validation of what the host answered happens in exactly one place.
96
+ */
97
+ export type EndpointEntry = {
98
+ readonly id: string;
99
+ readonly description: string;
100
+ /** Total: calls, catches, validates. Never rejects. */
101
+ readonly resolve: (context: JsonObject | undefined, signal?: AbortSignal) => Promise<Result<SubmissionTarget, SubmissionUnavailable>>;
102
+ };
103
+ /**
104
+ * Declares an endpoint. The target it answers with is validated even though the
105
+ * host typed it, for the reason `defineSource` validates an answer: the type is
106
+ * a claim made when the code was written, and the schema is what makes the
107
+ * claim true on the day the route moved.
108
+ */
109
+ export declare const defineEndpoint: (definition: EndpointDefinition) => EndpointEntry;
110
+ export type RegisteredEndpoint = EndpointEntry & {
111
+ readonly id: EndpointId;
112
+ };
113
+ export type EndpointRegistryError = {
114
+ readonly code: "invalid-endpoint-id";
115
+ readonly id: string;
116
+ } | {
117
+ readonly code: "duplicate-endpoint-id";
118
+ readonly id: string;
119
+ };
120
+ export declare const describeEndpointRegistryError: (error: EndpointRegistryError) => string;
121
+ export interface EndpointRegistry {
122
+ readonly endpoint: (id: EndpointId) => RegisteredEndpoint | undefined;
123
+ /** In registration order, so a catalogue reads predictably. */
124
+ readonly endpoints: readonly RegisteredEndpoint[];
125
+ }
126
+ /**
127
+ * Building the registry is pure and calls no endpoint, so registering cannot
128
+ * mint a token as a side effect of an import.
129
+ */
130
+ export declare const createEndpointRegistry: (entries: readonly EndpointEntry[]) => Result<EndpointRegistry, EndpointRegistryError>;
131
+ //# sourceMappingURL=endpoint.d.ts.map