@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,185 @@
1
+ import { z } from "zod";
2
+ import { proposalIdSchema, treeIdSchema } from "../ids.js";
3
+ import { clampLimit } from "../paging.js";
4
+ import { err, ok } from "../result.js";
5
+ import { dispositionSchema } from "../runtime/disposition.js";
6
+ import { editIntentSchema } from "../runtime/intent.js";
7
+ import { proposedChangeSchema } from "../runtime/proposal.js";
8
+ /**
9
+ * The same shape, as something a stored row can be checked against.
10
+ *
11
+ * It exists for the reason `dispositionSchema`'s comment gives: a hold outlives
12
+ * the process that created it, and a judgment restored from storage is validated
13
+ * at that boundary like anything else that crossed a wire or a year. Held here
14
+ * rather than in a backend so that every implementation reads a hold back the
15
+ * same way — a second store that parsed loosely would disagree with the first
16
+ * about what is storable, and the contract suite would not catch it because both
17
+ * would still round-trip their own writes.
18
+ */
19
+ /**
20
+ * Named rather than inlined because a cursor carries one back: a page of holds
21
+ * resumes from an instant and an id, and the instant it resumes from has to be
22
+ * held to the same shape on the way in as it was on the way out.
23
+ */
24
+ const heldAtSchema = z.string().datetime();
25
+ export const heldProposalSchema = z.object({
26
+ proposalId: proposalIdSchema,
27
+ treeId: treeIdSchema,
28
+ baseRevision: z.number().int().nonnegative(),
29
+ intent: editIntentSchema,
30
+ proposal: proposedChangeSchema,
31
+ disposition: dispositionSchema,
32
+ heldAt: heldAtSchema,
33
+ });
34
+ export const describeHoldError = (error) => {
35
+ switch (error.code) {
36
+ case "not-held":
37
+ return `no proposal is held under ${error.proposalId}; it may already have been answered`;
38
+ case "already-held":
39
+ return `${error.proposalId} is already held`;
40
+ case "unavailable":
41
+ return `the holding store is unavailable: ${error.detail}`;
42
+ case "unreadable":
43
+ return `the holding store returned something this build cannot read: ${error.detail}`;
44
+ }
45
+ };
46
+ /**
47
+ * Reads a hold back out of storage, or says why it could not.
48
+ *
49
+ * The assertion is about the shape of optionality and never about validity — the
50
+ * schema above establishes that. Zod infers an optional field as `T | undefined`,
51
+ * which `exactOptionalPropertyTypes` distinguishes from an absent key, while JSON
52
+ * has no `undefined` at all: a stored hold either carries `actor` or omits it,
53
+ * and never holds it as an explicit nothing. So the parsed value already has the
54
+ * shape the type asks for, and this is the one place that has to say so.
55
+ */
56
+ export const parseHeldProposal = (row) => {
57
+ const parsed = heldProposalSchema.safeParse(row);
58
+ return parsed.success
59
+ ? ok(parsed.data)
60
+ : err({
61
+ code: "unreadable",
62
+ detail: `a stored hold did not parse: ${parsed.error.issues[0]?.path.join(".") ?? "unknown"}`,
63
+ });
64
+ };
65
+ const compareStrings = (left, right) => {
66
+ if (left < right)
67
+ return -1;
68
+ return left > right ? 1 : 0;
69
+ };
70
+ /**
71
+ * The order both listings are in: oldest first, then by id.
72
+ *
73
+ * Written once and shared for the reason `pageEnds` and `anchorBound` are — it
74
+ * is the part most likely to drift between two backends and least likely to be
75
+ * noticed when it does. `postgresHoldStore` is the one caller that cannot use
76
+ * it, because ordering has to happen in the statement for an index to be usable;
77
+ * its `ORDER BY` names this function, and the contract suite is what holds the
78
+ * two to the same answer.
79
+ */
80
+ export const compareHolds = (left, right) => compareStrings(left.heldAt, right.heldAt) || compareStrings(left.proposalId, right.proposalId);
81
+ const CURSOR_SEPARATOR = " ";
82
+ export const holdCursor = (position) => `${position.heldAt}${CURSOR_SEPARATOR}${position.proposalId}`;
83
+ /**
84
+ * Reads a cursor back into the position it names, or says it cannot.
85
+ *
86
+ * Unreadable means the same thing here as everywhere else in Loom (see
87
+ * `cursorPosition`): start at the beginning, rather than one implementation
88
+ * refusing what another silently accepts. Both halves are checked, because a
89
+ * cursor that survived a URL is a value from outside — and a position built
90
+ * from an instant that is not one would compare against nonsense and page from
91
+ * somewhere no caller asked for. The separator is a space, which neither an
92
+ * RFC 3339 instant nor an id can contain.
93
+ */
94
+ export const holdCursorPosition = (cursor) => {
95
+ if (cursor === undefined)
96
+ return undefined;
97
+ const separator = cursor.indexOf(CURSOR_SEPARATOR);
98
+ if (separator === -1)
99
+ return undefined;
100
+ return holdPosition({
101
+ heldAt: cursor.slice(0, separator),
102
+ proposalId: cursor.slice(separator + 1),
103
+ });
104
+ };
105
+ /**
106
+ * The two columns a page is ordered by, checked, or nothing.
107
+ *
108
+ * Separate from reading a whole hold because it is a strictly smaller question
109
+ * and it is the one a listing cannot proceed without. A backend that skips the
110
+ * rows it could not read still has to page past them, and it can only do that
111
+ * if it can position them — so the position is parsed first and on its own,
112
+ * and a row that has one is a row the queue can always name and always get
113
+ * beyond, whatever its payload turned out to be.
114
+ */
115
+ export const holdPosition = (row) => {
116
+ const heldAt = heldAtSchema.safeParse(row.heldAt);
117
+ const proposalId = proposalIdSchema.safeParse(row.proposalId);
118
+ return heldAt.success && proposalId.success
119
+ ? { heldAt: heldAt.data, proposalId: proposalId.data }
120
+ : undefined;
121
+ };
122
+ /**
123
+ * Smaller than a tree listing's page, because a held proposal is the heaviest
124
+ * row this store keeps: a whole delta, the intent that asked for it, and the
125
+ * judgment that held it back. A reviewer reads them one at a time, so a page is
126
+ * sized for a screen rather than for a fold.
127
+ */
128
+ export const DEFAULT_HOLD_LIMIT = 25;
129
+ export const MAX_HOLD_LIMIT = 100;
130
+ export const clampHoldLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_HOLD_LIMIT, max: MAX_HOLD_LIMIT });
131
+ /**
132
+ * The reference implementation. Both listings are in `compareHolds` order, so a
133
+ * queue reads oldest-first: a change that has been waiting longest is the one
134
+ * most likely to be about to go stale.
135
+ */
136
+ export const memoryHoldStore = () => {
137
+ const held = new Map();
138
+ return {
139
+ hold: (proposal) => Promise.resolve(held.has(proposal.proposalId)
140
+ ? err({ code: "already-held", proposalId: proposal.proposalId })
141
+ : (() => {
142
+ held.set(proposal.proposalId, proposal);
143
+ return ok(proposal);
144
+ })()),
145
+ get: (proposalId) => {
146
+ const found = held.get(proposalId);
147
+ return Promise.resolve(found ? ok(found) : err({ code: "not-held", proposalId }));
148
+ },
149
+ forTree: (treeId) => Promise.resolve(ok({
150
+ held: Array.from(held.values())
151
+ .filter((proposal) => proposal.treeId === treeId)
152
+ .sort(compareHolds),
153
+ /**
154
+ * Always empty, and not because this implementation is careless: it
155
+ * holds parsed values rather than rows, so there is no such thing
156
+ * here as a hold it cannot read. The field is present so that a
157
+ * caller written against the contract reads the same shape from both
158
+ * stores and never branches on which one it was handed.
159
+ */
160
+ unreadable: [],
161
+ })),
162
+ waiting: (request) => {
163
+ const limit = clampHoldLimit(request?.limit);
164
+ const from = holdCursorPosition(request?.cursor);
165
+ const remaining = Array.from(held.values())
166
+ .sort(compareHolds)
167
+ .filter((proposal) => from === undefined || compareHolds(proposal, from) > 0);
168
+ const page = remaining.slice(0, limit);
169
+ const last = page.at(-1);
170
+ return Promise.resolve(ok({
171
+ held: page,
172
+ unreadable: [],
173
+ cursor: last !== undefined && remaining.length > page.length ? holdCursor(last) : null,
174
+ }));
175
+ },
176
+ release: (proposalId) => {
177
+ const found = held.get(proposalId);
178
+ if (!found)
179
+ return Promise.resolve(err({ code: "not-held", proposalId }));
180
+ held.delete(proposalId);
181
+ return Promise.resolve(ok(found));
182
+ },
183
+ };
184
+ };
185
+ //# sourceMappingURL=held.js.map
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Committing a judged change, and taking one back.
3
+ *
4
+ * The three operations that move a tree forward or backward in the store once the
5
+ * gate has had its say.
6
+ */
7
+ export * from "./commit.js";
8
+ export * from "./held.js";
9
+ export * from "./liveness.js";
10
+ export * from "./revert.js";
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Committing a judged change, and taking one back.
3
+ *
4
+ * The three operations that move a tree forward or backward in the store once the
5
+ * gate has had its say.
6
+ */
7
+ export * from "./commit.js";
8
+ export * from "./held.js";
9
+ export * from "./liveness.js";
10
+ export * from "./revert.js";
11
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,132 @@
1
+ import type { TreeId } from "../ids.js";
2
+ import type { StoreError } from "../store/errors.js";
3
+ import type { TreeReader } from "../store/store.js";
4
+ import type { HeldProposal } from "./held.js";
5
+ /**
6
+ * Which of the changes waiting for an answer can still happen.
7
+ *
8
+ * `confirmHeld` compares the revision a proposal was judged against to the head
9
+ * it would land on, and when they differ it releases the hold and reports
10
+ * `revision-conflict` — dead rather than stale, because the delta can never
11
+ * apply again and a second attempt at something impossible is worse than no
12
+ * attempt. That is the right behaviour and it arrives too late to be useful to
13
+ * the person doing the answering.
14
+ *
15
+ * Nothing said so beforehand. `forTree` hands back every waiting proposal with
16
+ * no reference to where the page has got to, and `waiting` does the same across
17
+ * a deployment, so a review queue built the documented way lists dead changes
18
+ * and live ones together, oldest first, indistinguishable. The only way to find
19
+ * out which is which was to answer one: read the change, decide, click yes, and
20
+ * be told it never could have worked. Filed by `Loom docs` on 7 September, who
21
+ * met it writing *When something looks wrong* and taught it on the page because
22
+ * it was true.
23
+ *
24
+ * The comparison is one line, which is the reason it belongs here rather than in
25
+ * every host: it has a direction, `confirmHeld` already fixed which one, and a
26
+ * queue that got it backwards would badge exactly the wrong half.
27
+ */
28
+ /**
29
+ * What can be said about a hold, given what is known about its tree.
30
+ *
31
+ * `unknown` is a third answer rather than an optimistic `live` because the
32
+ * question is asked over a page of holds spanning many trees, and a head that
33
+ * could not be read is not evidence that nothing moved. A queue that shows no
34
+ * badge is honest; one that shows *live* on a tree nobody could reach is the
35
+ * failure this module exists to remove, restated one level up.
36
+ */
37
+ export type HoldLiveness = "live" | "dead" | "unknown";
38
+ /**
39
+ * The three answers, as a list a host can walk.
40
+ *
41
+ * The shape settled in `closed-set.ts`, here for the usual reason: a queue wants
42
+ * a bucket per answer to exist before the first row arrives, and a legend wants
43
+ * to describe all three without keeping its own copy of them.
44
+ */
45
+ export declare const HOLD_LIVENESS: readonly HoldLiveness[];
46
+ /**
47
+ * The one comparison, in the direction `confirmHeld` makes it.
48
+ *
49
+ * Inequality rather than `headRevision > hold.baseRevision`, deliberately: the
50
+ * write path refuses any head that is not the exact revision the Gate judged
51
+ * against, so a hold naming a revision ahead of head — which a log cannot
52
+ * produce, and a restored backup or a mistyped fixture can — is dead by the same
53
+ * rule that will refuse it. A helper that judged it live would disagree with the
54
+ * only opinion that matters.
55
+ *
56
+ * A head of `undefined` means the caller has no revision for this tree, and the
57
+ * answer is `unknown`. It is not an error: the two listings are unpaged and
58
+ * paged respectively, and a caller assembling heads for a page of holds may
59
+ * legitimately be missing one.
60
+ */
61
+ export declare const holdLiveness: (hold: HeldProposal, headRevision: number | undefined) => HoldLiveness;
62
+ /**
63
+ * A hold and what is known about whether answering it could work.
64
+ *
65
+ * `headRevision` is carried rather than left for the caller to look up again
66
+ * because a queue that badges a row wants to say what it compared — *held
67
+ * against 3, the page is at 4* is the sentence that stops a reviewer wondering
68
+ * whether the badge is a bug.
69
+ */
70
+ export type MarkedHold = {
71
+ readonly held: HeldProposal;
72
+ readonly liveness: HoldLiveness;
73
+ /** Absent exactly when `liveness` is `unknown`. */
74
+ readonly headRevision?: number;
75
+ };
76
+ /**
77
+ * Marks a page of holds against the revisions the caller already knows.
78
+ *
79
+ * Pure, and total: every hold comes back marked, in the order it arrived, so a
80
+ * queue keeps `compareHolds` order and gains a column. Holds against a tree the
81
+ * map does not name are `unknown` rather than dropped — a listing that quietly
82
+ * lost rows because a head was missing would be a worse failure than the one
83
+ * this fixes.
84
+ */
85
+ export declare const markHolds: (holds: readonly HeldProposal[], heads: ReadonlyMap<TreeId, number>) => readonly MarkedHold[];
86
+ /**
87
+ * The trees a page of holds is waiting on, each named once, in first-seen order.
88
+ *
89
+ * A queue reads one head per tree and not one per hold: three changes held
90
+ * against the same page are three rows and one question. First-seen order rather
91
+ * than sorted, so the reads a caller issues follow the order the holds are shown
92
+ * in and the first row on screen is the first one answered.
93
+ */
94
+ export declare const treesAwaitingAnswer: (holds: readonly HeldProposal[]) => readonly TreeId[];
95
+ /**
96
+ * The same page of holds, marked against heads read from the store.
97
+ *
98
+ * What a host would otherwise write, and the reason to write it once: read each
99
+ * distinct head, compare in the direction the write path compares, keep the
100
+ * order.
101
+ */
102
+ export type MarkedHolds = {
103
+ readonly marked: readonly MarkedHold[];
104
+ /**
105
+ * One per tree whose head could not be read. Those holds are `unknown`, and
106
+ * the errors are handed back rather than swallowed so a host can log them or
107
+ * say so on the page.
108
+ */
109
+ readonly unreadable: readonly StoreError[];
110
+ };
111
+ /**
112
+ * Reads what it needs and never fails.
113
+ *
114
+ * A `Result` was the first shape and is the wrong one. A queue over every page
115
+ * of a deployment spans many trees, and one tree being unavailable is not a
116
+ * reason for a reviewer to see nothing: the honest answer is the rest of the
117
+ * queue badged and that tree's rows unbadged. Fail-fast would have made this
118
+ * module's own point — *say what you cannot say, rather than guessing* —
119
+ * unavailable to the caller in exactly the case it was written for.
120
+ *
121
+ * `not-found` is `unknown` and not `dead`, which is the one classification here
122
+ * worth arguing with. A hold against a tree that is not there cannot be
123
+ * confirmed either — but it fails as `not-found`, not as a revision conflict,
124
+ * and a badge reading *the page moved on* about a page that is gone would be a
125
+ * true-sounding sentence about the wrong fault. This predicate answers one
126
+ * question and declines the neighbouring one.
127
+ *
128
+ * `TreeReader` rather than `TreeStore`, because badging a queue is a read and
129
+ * nothing here should be handed something that can append.
130
+ */
131
+ export declare const markHoldsFromStore: (reader: TreeReader, holds: readonly HeldProposal[]) => Promise<MarkedHolds>;
132
+ //# sourceMappingURL=liveness.d.ts.map
@@ -0,0 +1,91 @@
1
+ import { everyMemberOf } from "../closed-set.js";
2
+ /**
3
+ * The three answers, as a list a host can walk.
4
+ *
5
+ * The shape settled in `closed-set.ts`, here for the usual reason: a queue wants
6
+ * a bucket per answer to exist before the first row arrives, and a legend wants
7
+ * to describe all three without keeping its own copy of them.
8
+ */
9
+ export const HOLD_LIVENESS = everyMemberOf()([
10
+ "live",
11
+ "dead",
12
+ "unknown",
13
+ ]);
14
+ /**
15
+ * The one comparison, in the direction `confirmHeld` makes it.
16
+ *
17
+ * Inequality rather than `headRevision > hold.baseRevision`, deliberately: the
18
+ * write path refuses any head that is not the exact revision the Gate judged
19
+ * against, so a hold naming a revision ahead of head — which a log cannot
20
+ * produce, and a restored backup or a mistyped fixture can — is dead by the same
21
+ * rule that will refuse it. A helper that judged it live would disagree with the
22
+ * only opinion that matters.
23
+ *
24
+ * A head of `undefined` means the caller has no revision for this tree, and the
25
+ * answer is `unknown`. It is not an error: the two listings are unpaged and
26
+ * paged respectively, and a caller assembling heads for a page of holds may
27
+ * legitimately be missing one.
28
+ */
29
+ export const holdLiveness = (hold, headRevision) => {
30
+ if (headRevision === undefined)
31
+ return "unknown";
32
+ return headRevision === hold.baseRevision ? "live" : "dead";
33
+ };
34
+ /**
35
+ * Marks a page of holds against the revisions the caller already knows.
36
+ *
37
+ * Pure, and total: every hold comes back marked, in the order it arrived, so a
38
+ * queue keeps `compareHolds` order and gains a column. Holds against a tree the
39
+ * map does not name are `unknown` rather than dropped — a listing that quietly
40
+ * lost rows because a head was missing would be a worse failure than the one
41
+ * this fixes.
42
+ */
43
+ export const markHolds = (holds, heads) => holds.map((held) => {
44
+ const headRevision = heads.get(held.treeId);
45
+ const liveness = holdLiveness(held, headRevision);
46
+ return headRevision === undefined ? { held, liveness } : { held, liveness, headRevision };
47
+ });
48
+ /**
49
+ * The trees a page of holds is waiting on, each named once, in first-seen order.
50
+ *
51
+ * A queue reads one head per tree and not one per hold: three changes held
52
+ * against the same page are three rows and one question. First-seen order rather
53
+ * than sorted, so the reads a caller issues follow the order the holds are shown
54
+ * in and the first row on screen is the first one answered.
55
+ */
56
+ export const treesAwaitingAnswer = (holds) => [
57
+ ...new Set(holds.map((held) => held.treeId)),
58
+ ];
59
+ /**
60
+ * Reads what it needs and never fails.
61
+ *
62
+ * A `Result` was the first shape and is the wrong one. A queue over every page
63
+ * of a deployment spans many trees, and one tree being unavailable is not a
64
+ * reason for a reviewer to see nothing: the honest answer is the rest of the
65
+ * queue badged and that tree's rows unbadged. Fail-fast would have made this
66
+ * module's own point — *say what you cannot say, rather than guessing* —
67
+ * unavailable to the caller in exactly the case it was written for.
68
+ *
69
+ * `not-found` is `unknown` and not `dead`, which is the one classification here
70
+ * worth arguing with. A hold against a tree that is not there cannot be
71
+ * confirmed either — but it fails as `not-found`, not as a revision conflict,
72
+ * and a badge reading *the page moved on* about a page that is gone would be a
73
+ * true-sounding sentence about the wrong fault. This predicate answers one
74
+ * question and declines the neighbouring one.
75
+ *
76
+ * `TreeReader` rather than `TreeStore`, because badging a queue is a read and
77
+ * nothing here should be handed something that can append.
78
+ */
79
+ export const markHoldsFromStore = async (reader, holds) => {
80
+ const heads = new Map();
81
+ const unreadable = [];
82
+ for (const treeId of treesAwaitingAnswer(holds)) {
83
+ const head = await reader.head(treeId);
84
+ if (head.ok)
85
+ heads.set(treeId, head.value.revision);
86
+ else
87
+ unreadable.push(head.error);
88
+ }
89
+ return { marked: markHolds(holds, heads), unreadable };
90
+ };
91
+ //# sourceMappingURL=liveness.js.map
@@ -0,0 +1,79 @@
1
+ import type { IdFactory, TreeId } from "../ids.js";
2
+ import type { Clock } from "../runtime/events.js";
3
+ import type { IntentOrigin } from "../runtime/intent.js";
4
+ import type { ChangeInterpreter } from "../runtime/interpreter.js";
5
+ import { type RevertPlan, type UnrevertablePlan } from "../store/revert.js";
6
+ import type { LoomTree } from "../tree/tree.js";
7
+ import { type WriteOutcome, type WritePath } from "./commit.js";
8
+ /**
9
+ * Undo, as a change like any other.
10
+ *
11
+ * The runtime has always been able to *say* a change is reversible — the
12
+ * inverse delta is computed at assessment time and carried through the
13
+ * pipeline. Nothing applied it, so "reversible" was a claim the runtime made
14
+ * about itself and never had to honour.
15
+ *
16
+ * This honours it without giving undo a private route. A revert is interpreted
17
+ * (deterministically), proposed, assessed, gated, applied, and appended to the
18
+ * log as a new revision — the same seven steps every other change takes. It is
19
+ * therefore attributable to whoever asked for it, refusable by the Gate,
20
+ * holdable for confirmation, visible to telemetry, and itself revertable.
21
+ *
22
+ * The alternative — rewinding the log, or applying the inverse straight to the
23
+ * store — would make undo the one operation that changes a tree without being
24
+ * judged, and the log the one record with a hole in it (0032).
25
+ *
26
+ * An undo whose target was built on afterwards is offered rather than refused
27
+ * (0035). What made it refusable was that the Gate could not see the difference
28
+ * between a clean undo and one that writes over later work; now the plan says so
29
+ * and the proposal carries the declaration, so the Gate holds it for a person
30
+ * instead of the runtime deciding on their behalf that they may not have it.
31
+ */
32
+ /** What produced the delta, for `Provenance.interpreter`. Not a model. */
33
+ export declare const REVERT_INTERPRETER = "loom/revert";
34
+ export type RevertablePlan = Extract<RevertPlan, {
35
+ readonly outcome: "revertable";
36
+ }>;
37
+ /**
38
+ * The same interpreter every undo uses, with the log's half filled in.
39
+ *
40
+ * Everything specific to a revert is here — the stamp that says this came off a
41
+ * log, the rationale that names the revision and what it costs, and the work the
42
+ * plan found to declare. What is left is `inverseInterpreter`, which a surface
43
+ * with no store reaches for directly: the head check, the provenance of a
44
+ * computed change, and the shape of the proposal are one implementation rather
45
+ * than two that drift.
46
+ */
47
+ export declare const revertInterpreter: (plan: RevertablePlan, idFactory: IdFactory, clock: Clock) => ChangeInterpreter;
48
+ export type RevertRequest = {
49
+ readonly treeId: TreeId;
50
+ /** The revision to undo. */
51
+ readonly revision: number;
52
+ /** Replayed from, to recover the tree the target's delta observed (0028). */
53
+ readonly seed: LoomTree;
54
+ readonly origin: IntentOrigin;
55
+ readonly actor?: string;
56
+ };
57
+ export type RevertOutcome = WriteOutcome
58
+ /**
59
+ * Nothing was proposed, because no undo could be computed: the revision is
60
+ * outside the span the seed reaches, the log does not replay, or the delta does
61
+ * not invert. Work the undo would write over is not one of these — that is a
62
+ * proposal the Gate holds, not a plan that failed (0035).
63
+ */
64
+ | {
65
+ readonly kind: "not-revertable";
66
+ readonly plan: UnrevertablePlan;
67
+ };
68
+ export declare const describeRevertOutcome: (outcome: RevertOutcome) => string;
69
+ /**
70
+ * Undoes a revision, if the log allows it and the Gate agrees.
71
+ *
72
+ * The intent is synthesised here rather than taken from the caller, because the
73
+ * utterance behind a revert is not a sentence someone typed — it is the
74
+ * revision number they named. `origin` and `actor` are the caller's, and they
75
+ * are what the Gate weighs and what provenance records: undoing a change is
76
+ * still someone asking for a change.
77
+ */
78
+ export declare const revertRevision: (path: WritePath, request: RevertRequest) => Promise<RevertOutcome>;
79
+ //# sourceMappingURL=revert.d.ts.map
@@ -0,0 +1,134 @@
1
+ import { inverseInterpreter } from "../runtime/inverse.js";
2
+ import { describeRevertPlan, planRevert } from "../store/revert.js";
3
+ import { commitIntent, describeWriteOutcome } from "./commit.js";
4
+ /**
5
+ * Undo, as a change like any other.
6
+ *
7
+ * The runtime has always been able to *say* a change is reversible — the
8
+ * inverse delta is computed at assessment time and carried through the
9
+ * pipeline. Nothing applied it, so "reversible" was a claim the runtime made
10
+ * about itself and never had to honour.
11
+ *
12
+ * This honours it without giving undo a private route. A revert is interpreted
13
+ * (deterministically), proposed, assessed, gated, applied, and appended to the
14
+ * log as a new revision — the same seven steps every other change takes. It is
15
+ * therefore attributable to whoever asked for it, refusable by the Gate,
16
+ * holdable for confirmation, visible to telemetry, and itself revertable.
17
+ *
18
+ * The alternative — rewinding the log, or applying the inverse straight to the
19
+ * store — would make undo the one operation that changes a tree without being
20
+ * judged, and the log the one record with a hole in it (0032).
21
+ *
22
+ * An undo whose target was built on afterwards is offered rather than refused
23
+ * (0035). What made it refusable was that the Gate could not see the difference
24
+ * between a clean undo and one that writes over later work; now the plan says so
25
+ * and the proposal carries the declaration, so the Gate holds it for a person
26
+ * instead of the runtime deciding on their behalf that they may not have it.
27
+ */
28
+ /** What produced the delta, for `Provenance.interpreter`. Not a model. */
29
+ export const REVERT_INTERPRETER = "loom/revert";
30
+ /**
31
+ * What the undo is for, and — when there is one — what it costs.
32
+ *
33
+ * The cost is spelled out in the rationale as well as declared in `discards`,
34
+ * because the two are read by different readers: the Gate reads the declaration,
35
+ * and the person answering the hold reads this (0019 — the portal shows a
36
+ * reviewer the reason, not a verdict).
37
+ */
38
+ const rationaleFor = (plan) => {
39
+ const undoes = `Undoes revision ${plan.target.revision}, applied ${plan.target.appliedAt} from proposal ${plan.target.proposalId}.`;
40
+ if (plan.discards.length === 0)
41
+ return undoes;
42
+ const revisions = plan.discards.map((discarded) => discarded.revision).join(", ");
43
+ return `${undoes} Revision${plan.discards.length === 1 ? "" : "s"} ${revisions} changed nodes this undo touches, and applying it writes over what they did.`;
44
+ };
45
+ /**
46
+ * The same interpreter every undo uses, with the log's half filled in.
47
+ *
48
+ * Everything specific to a revert is here — the stamp that says this came off a
49
+ * log, the rationale that names the revision and what it costs, and the work the
50
+ * plan found to declare. What is left is `inverseInterpreter`, which a surface
51
+ * with no store reaches for directly: the head check, the provenance of a
52
+ * computed change, and the shape of the proposal are one implementation rather
53
+ * than two that drift.
54
+ */
55
+ export const revertInterpreter = (plan, idFactory, clock) => inverseInterpreter({
56
+ operations: plan.operations,
57
+ /**
58
+ * The plan's contest check was made against one head. Judging it at a
59
+ * different one would be judging a different question, so the interpreter
60
+ * declines rather than proposing something whose reasoning has expired.
61
+ * The write path refuses a moved head before reaching here; this is what
62
+ * keeps the interpreter safe to wire into a runtime directly.
63
+ */
64
+ headRevision: plan.headRevision,
65
+ interpreter: REVERT_INTERPRETER,
66
+ rationale: rationaleFor(plan),
67
+ /**
68
+ * The same number the rationale states in a sentence, as a field. The
69
+ * sentence is for the person answering a hold; this is for the surface
70
+ * reading the log afterwards, which until now could only have the sentence.
71
+ */
72
+ undoes: plan.target.revision,
73
+ /**
74
+ * Declared only when there is something to declare, so absence keeps
75
+ * meaning "nobody looked at a log" rather than "a log was checked and was
76
+ * clean" (0035).
77
+ */
78
+ ...(plan.discards.length === 0 ? {} : { discards: plan.discards }),
79
+ }, idFactory, clock);
80
+ export const describeRevertOutcome = (outcome) => outcome.kind === "not-revertable"
81
+ ? `not revertable: ${describeRevertPlan(outcome.plan)}`
82
+ : describeWriteOutcome(outcome);
83
+ /**
84
+ * The same runtime, interpreting reverts.
85
+ *
86
+ * Built field by field rather than spread, so that dropping the repairer is a
87
+ * statement instead of an omission: repair (0006) exists to let a model try a
88
+ * smaller version of what the Gate refused, and there is no smaller version of
89
+ * an undo. A revert the Gate refuses is refused.
90
+ */
91
+ const revertingRuntime = (runtime, interpreter) => ({
92
+ interpreter,
93
+ policySource: runtime.policySource,
94
+ events: runtime.events,
95
+ clock: runtime.clock,
96
+ idFactory: runtime.idFactory,
97
+ });
98
+ /**
99
+ * Undoes a revision, if the log allows it and the Gate agrees.
100
+ *
101
+ * The intent is synthesised here rather than taken from the caller, because the
102
+ * utterance behind a revert is not a sentence someone typed — it is the
103
+ * revision number they named. `origin` and `actor` are the caller's, and they
104
+ * are what the Gate weighs and what provenance records: undoing a change is
105
+ * still someone asking for a change.
106
+ */
107
+ export const revertRevision = async (path, request) => {
108
+ const planned = await planRevert(path.store, {
109
+ treeId: request.treeId,
110
+ revision: request.revision,
111
+ seed: request.seed,
112
+ });
113
+ if (!planned.ok)
114
+ return { kind: "not-written", error: planned.error };
115
+ if (planned.value.outcome !== "revertable")
116
+ return { kind: "not-revertable", plan: planned.value };
117
+ const plan = planned.value;
118
+ const { idFactory, clock } = path.runtime;
119
+ const intent = {
120
+ intentId: idFactory.intentId(),
121
+ treeId: request.treeId,
122
+ baseRevision: plan.headRevision,
123
+ origin: request.origin,
124
+ ...(request.actor === undefined ? {} : { actor: request.actor }),
125
+ utterance: `Undo revision ${request.revision}.`,
126
+ observedAt: clock.now(),
127
+ };
128
+ return commitIntent({
129
+ store: path.store,
130
+ holds: path.holds,
131
+ runtime: revertingRuntime(path.runtime, revertInterpreter(plan, idFactory, clock)),
132
+ }, intent);
133
+ };
134
+ //# sourceMappingURL=revert.js.map