@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,405 @@
1
+ import { z } from "zod";
2
+ import { intentIdSchema, nodeIdSchema, proposalIdSchema, treeIdSchema, } from "../ids.js";
3
+ import { primitiveTypeSchema } from "../primitive-type.js";
4
+ import { assertNever } from "../result.js";
5
+ import { dispositionReasonSchema, dispositionSchema, } from "../runtime/disposition.js";
6
+ import { intentOriginSchema } from "../runtime/intent.js";
7
+ import { policyFingerprintOf } from "../runtime/policy-fingerprint.js";
8
+ import { proposedChangeSchema } from "../runtime/proposal.js";
9
+ import { stakeLevelSchema } from "../runtime/stake-level.js";
10
+ import { describeStoreError } from "../store/errors.js";
11
+ import { describeTreeError } from "../tree/errors.js";
12
+ /**
13
+ * What §6 keeps, and what it deliberately does not.
14
+ *
15
+ * A `RuntimeEvent` is the runtime talking to itself in a single process: it
16
+ * carries whole assessments and whole inverse deltas because the next stage
17
+ * needs them. A telemetry record is what survives the request, so it is a
18
+ * narrowing of that stream rather than a copy of it (0023). Three rules decide
19
+ * what crosses:
20
+ *
21
+ * - **The delta of a proposal is kept.** For a change that was refused, held and
22
+ * discarded, or never applied, this journal is the only record it ever
23
+ * existed — the revision log by construction holds only what was applied.
24
+ * - **Anything the log already holds is dropped.** An applied change's inverse
25
+ * is in the log with its provenance, and storing it twice invites two stores
26
+ * to disagree about the same delta.
27
+ * - **The utterance is not kept.** Telemetry is retained and aggregated; what
28
+ * someone typed is content, and provenance's `promptHash` already exists for
29
+ * hosts that want to group identical asks without keeping their text.
30
+ *
31
+ * The event names mirror `RuntimeEvent` one for one. A stage the runtime
32
+ * narrates but telemetry silently discarded would be a stage nobody could prove
33
+ * ran, so narrowing changes payloads and never membership.
34
+ *
35
+ * A field added after records exist is **optional and never defaulted** (0045).
36
+ * A record written before a field existed did not decline to say it — it could
37
+ * not, and a default would put a number in its mouth.
38
+ */
39
+ /**
40
+ * A failure, as telemetry stores it: the code, and a sentence the runtime wrote
41
+ * about it. `code` is an open string rather than a mirror of §1/§2/§5's error
42
+ * taxonomies on purpose — adding an error code somewhere else in the codebase
43
+ * must not make records written yesterday fail to parse today.
44
+ */
45
+ export const telemetryFailureSchema = z.object({
46
+ code: z.string().min(1),
47
+ detail: z.string().min(1),
48
+ });
49
+ /**
50
+ * The intent, minus what was said. Origin, scope and the revision it was aimed
51
+ * at are what an analysis needs; `utteranceLength` keeps "a one-word ask" and
52
+ * "three paragraphs" distinguishable without storing either.
53
+ *
54
+ * `actor` is kept for the same reason `origin` is: it is an identifier a query
55
+ * groups by, not content someone typed. The rule 0023 set is about the
56
+ * utterance, and an identity is on the other side of it.
57
+ */
58
+ export const intentSummarySchema = z.object({
59
+ intentId: intentIdSchema,
60
+ origin: intentOriginSchema,
61
+ actor: z.string().min(1).optional(),
62
+ baseRevision: z.number().int().nonnegative(),
63
+ scopeNodeId: nodeIdSchema.optional(),
64
+ utteranceLength: z.number().int().nonnegative(),
65
+ observedAt: z.string().datetime(),
66
+ });
67
+ /**
68
+ * What the Gate was looking at, in the shape a query can group by. The
69
+ * disposition that follows says stakes, reversibility and confidence; this says
70
+ * how big the change was and what it touched, which is what makes "the Gate
71
+ * refuses this class of change" measurable rather than anecdotal.
72
+ */
73
+ export const assessmentSummarySchema = z.object({
74
+ proposalId: proposalIdSchema,
75
+ stakes: stakeLevelSchema,
76
+ reversible: z.boolean(),
77
+ operationCount: z.number().int().nonnegative(),
78
+ insertedNodeCount: z.number().int().nonnegative(),
79
+ removedNodeCount: z.number().int().nonnegative(),
80
+ movedNodeCount: z.number().int().nonnegative(),
81
+ configuredNodeCount: z.number().int().nonnegative(),
82
+ touchedPrimitiveTypes: z.array(primitiveTypeSchema),
83
+ /**
84
+ * Bounded, non-identifying, a subset of the touched types, and the input to
85
+ * the only `critical` stake factor. A corpus that cannot group by "the Gate
86
+ * saw this type destroyed" cannot ask the question the factor exists for.
87
+ */
88
+ removedPrimitiveTypes: z.array(primitiveTypeSchema).optional(),
89
+ relocatedPrimitiveTypes: z.array(primitiveTypeSchema).optional(),
90
+ relocatedNodeCount: z.number().int().nonnegative().optional(),
91
+ shallowestAffectedDepth: z.number().int().nonnegative(),
92
+ /** Nodes the inverse would have to carry — the content a removal destroyed. */
93
+ retainedNodeCount: z.number().int().nonnegative(),
94
+ irreversibilityReasons: z.array(z.string().min(1)),
95
+ });
96
+ export const telemetryEventSchema = z.discriminatedUnion("type", [
97
+ z.object({ type: z.literal("intent-received"), intent: intentSummarySchema }),
98
+ z.object({
99
+ type: z.literal("policy-resolved"),
100
+ intentId: intentIdSchema,
101
+ policyId: z.string().min(1),
102
+ policyFingerprint: z.string().min(1).optional(),
103
+ }),
104
+ z.object({
105
+ type: z.literal("interpretation-failed"),
106
+ intentId: intentIdSchema,
107
+ failure: telemetryFailureSchema,
108
+ }),
109
+ z.object({ type: z.literal("change-proposed"), proposal: proposedChangeSchema }),
110
+ z.object({
111
+ type: z.literal("assessment-failed"),
112
+ proposalId: proposalIdSchema,
113
+ failure: telemetryFailureSchema,
114
+ }),
115
+ z.object({ type: z.literal("change-assessed"), assessment: assessmentSummarySchema }),
116
+ z.object({
117
+ type: z.literal("disposition-decided"),
118
+ proposalId: proposalIdSchema,
119
+ disposition: dispositionSchema,
120
+ }),
121
+ z.object({
122
+ type: z.literal("repair-requested"),
123
+ refusedProposalId: proposalIdSchema,
124
+ reason: dispositionReasonSchema,
125
+ }),
126
+ z.object({
127
+ type: z.literal("repair-failed"),
128
+ refusedProposalId: proposalIdSchema,
129
+ failure: telemetryFailureSchema,
130
+ }),
131
+ z.object({
132
+ type: z.literal("change-applied"),
133
+ proposalId: proposalIdSchema,
134
+ revision: z.number().int().nonnegative(),
135
+ }),
136
+ z.object({
137
+ type: z.literal("application-failed"),
138
+ proposalId: proposalIdSchema,
139
+ failure: telemetryFailureSchema,
140
+ }),
141
+ z.object({
142
+ type: z.literal("intent-not-writable"),
143
+ intentId: intentIdSchema,
144
+ failure: telemetryFailureSchema,
145
+ }),
146
+ z.object({ type: z.literal("proposal-held"), proposalId: proposalIdSchema }),
147
+ z.object({
148
+ type: z.literal("hold-failed"),
149
+ proposalId: proposalIdSchema,
150
+ failure: telemetryFailureSchema,
151
+ }),
152
+ z.object({
153
+ type: z.literal("hold-confirmed"),
154
+ proposalId: proposalIdSchema,
155
+ actor: z.string().min(1).optional(),
156
+ }),
157
+ z.object({
158
+ type: z.literal("hold-discarded"),
159
+ proposalId: proposalIdSchema,
160
+ actor: z.string().min(1).optional(),
161
+ }),
162
+ z.object({
163
+ type: z.literal("change-committed"),
164
+ proposalId: proposalIdSchema,
165
+ revision: z.number().int().nonnegative(),
166
+ }),
167
+ z.object({
168
+ type: z.literal("commit-failed"),
169
+ proposalId: proposalIdSchema,
170
+ failure: telemetryFailureSchema,
171
+ }),
172
+ ]);
173
+ /**
174
+ * Every event the journal can hold, in the order the runtime writes them.
175
+ *
176
+ * `TelemetryEvent` is exhaustive in a `switch` and that is the case it was built
177
+ * for. What it cannot answer is **how many**, and three things ask: a page that
178
+ * says what fraction of the vocabulary it is showing, a dashboard that needs
179
+ * every bucket to exist before the first request rather than discovering them as
180
+ * they arrive, and anything checking a sink against §6. Each of those otherwise
181
+ * keeps its own copy, in its own order, with nothing to fail when a nineteenth
182
+ * lands.
183
+ *
184
+ * The order is the lifecycle rather than the alphabet: an episode reads
185
+ * top to bottom, so a list printed in this order is a story and a list sorted by
186
+ * name is eighteen strings. `event.test.ts` holds it against
187
+ * `telemetryEventSchema`, which is what keeps it complete — the schema is the
188
+ * boundary a record has to cross, so a type the schema accepts and this omits is
189
+ * the drift worth failing over.
190
+ */
191
+ export const TELEMETRY_EVENT_TYPES = [
192
+ "intent-received",
193
+ "policy-resolved",
194
+ "interpretation-failed",
195
+ "change-proposed",
196
+ "assessment-failed",
197
+ "change-assessed",
198
+ "disposition-decided",
199
+ "repair-requested",
200
+ "repair-failed",
201
+ "change-applied",
202
+ "application-failed",
203
+ "intent-not-writable",
204
+ "proposal-held",
205
+ "hold-failed",
206
+ "hold-confirmed",
207
+ "hold-discarded",
208
+ "change-committed",
209
+ "commit-failed",
210
+ ];
211
+ export const telemetryRecordSchema = z.object({
212
+ treeId: treeIdSchema,
213
+ occurredAt: z.string().datetime(),
214
+ event: telemetryEventSchema,
215
+ });
216
+ const summariseIntent = (intent) => ({
217
+ intentId: intent.intentId,
218
+ origin: intent.origin,
219
+ ...(intent.actor === undefined ? {} : { actor: intent.actor }),
220
+ baseRevision: intent.baseRevision,
221
+ ...(intent.scopeNodeId ? { scopeNodeId: intent.scopeNodeId } : {}),
222
+ utteranceLength: intent.utterance.length,
223
+ observedAt: intent.observedAt,
224
+ });
225
+ const summariseAssessment = (assessment) => ({
226
+ proposalId: assessment.proposal.proposalId,
227
+ stakes: assessment.stakes.level,
228
+ reversible: assessment.reversibility.reversible,
229
+ operationCount: assessment.analysis.operationCount,
230
+ insertedNodeCount: assessment.analysis.insertedNodeCount,
231
+ removedNodeCount: assessment.analysis.removedNodeCount,
232
+ movedNodeCount: assessment.analysis.movedNodeCount,
233
+ configuredNodeCount: assessment.analysis.configuredNodeCount,
234
+ touchedPrimitiveTypes: assessment.analysis.touchedPrimitiveTypes,
235
+ removedPrimitiveTypes: assessment.analysis.removedPrimitiveTypes,
236
+ relocatedPrimitiveTypes: assessment.analysis.relocatedPrimitiveTypes,
237
+ relocatedNodeCount: assessment.analysis.relocatedNodeCount,
238
+ shallowestAffectedDepth: assessment.analysis.shallowestAffectedDepth,
239
+ retainedNodeCount: assessment.reversibility.retainedNodeCount,
240
+ irreversibilityReasons: assessment.reversibility.reasons.map((reason) => reason.code),
241
+ });
242
+ /**
243
+ * The narrowing, as one total function. Every variant is handled and the
244
+ * exhaustiveness guard is what makes adding a `RuntimeEvent` a compile error
245
+ * here rather than an event that silently never reaches the journal.
246
+ */
247
+ const narrowEvent = (event) => {
248
+ switch (event.type) {
249
+ case "intent-received":
250
+ return { type: "intent-received", intent: summariseIntent(event.intent) };
251
+ /**
252
+ * The name crosses; the values do not. A policy is host configuration that
253
+ * changes rarely and is versioned where the host keeps it, so copying it
254
+ * onto every change would store one document a million times to answer a
255
+ * question the name already answers.
256
+ *
257
+ * The fingerprint is what makes that contract checkable rather than merely
258
+ * stated (0048). It is a digest, not the document: bounded, and it answers
259
+ * "did this name keep meaning one thing" without keeping a copy of the
260
+ * configuration on every change.
261
+ */
262
+ case "policy-resolved":
263
+ return {
264
+ type: "policy-resolved",
265
+ intentId: event.intentId,
266
+ policyId: event.policy.policyId,
267
+ policyFingerprint: policyFingerprintOf(event.policy),
268
+ };
269
+ case "interpretation-failed":
270
+ return {
271
+ type: "interpretation-failed",
272
+ intentId: event.intent.intentId,
273
+ failure: { code: event.error.code, detail: event.error.detail },
274
+ };
275
+ case "change-proposed":
276
+ return { type: "change-proposed", proposal: event.proposal };
277
+ case "assessment-failed":
278
+ return {
279
+ type: "assessment-failed",
280
+ proposalId: event.proposal.proposalId,
281
+ failure: { code: event.error.code, detail: describeTreeError(event.error) },
282
+ };
283
+ case "change-assessed":
284
+ return { type: "change-assessed", assessment: summariseAssessment(event.assessment) };
285
+ case "disposition-decided":
286
+ return {
287
+ type: "disposition-decided",
288
+ proposalId: event.proposalId,
289
+ disposition: event.disposition,
290
+ };
291
+ case "repair-requested":
292
+ return {
293
+ type: "repair-requested",
294
+ refusedProposalId: event.refusedProposalId,
295
+ reason: event.reason,
296
+ };
297
+ case "repair-failed":
298
+ return {
299
+ type: "repair-failed",
300
+ refusedProposalId: event.refusedProposalId,
301
+ failure: { code: event.error.code, detail: event.error.detail },
302
+ };
303
+ /** The inverse is dropped: it is in the log, attached to the revision named here. */
304
+ case "change-applied":
305
+ return { type: "change-applied", proposalId: event.proposalId, revision: event.revision };
306
+ case "application-failed":
307
+ return {
308
+ type: "application-failed",
309
+ proposalId: event.proposalId,
310
+ failure: { code: event.error.code, detail: describeTreeError(event.error) },
311
+ };
312
+ case "intent-not-writable":
313
+ return {
314
+ type: "intent-not-writable",
315
+ intentId: event.intent.intentId,
316
+ failure: { code: event.error.code, detail: describeStoreError(event.error) },
317
+ };
318
+ case "proposal-held":
319
+ return { type: "proposal-held", proposalId: event.proposalId };
320
+ case "hold-failed":
321
+ return {
322
+ type: "hold-failed",
323
+ proposalId: event.proposalId,
324
+ failure: { code: "hold-failed", detail: event.detail },
325
+ };
326
+ case "hold-confirmed":
327
+ return {
328
+ type: "hold-confirmed",
329
+ proposalId: event.proposalId,
330
+ ...(event.actor === undefined ? {} : { actor: event.actor }),
331
+ };
332
+ case "hold-discarded":
333
+ return {
334
+ type: "hold-discarded",
335
+ proposalId: event.proposalId,
336
+ ...(event.actor === undefined ? {} : { actor: event.actor }),
337
+ };
338
+ case "change-committed":
339
+ return { type: "change-committed", proposalId: event.proposalId, revision: event.revision };
340
+ case "commit-failed":
341
+ return {
342
+ type: "commit-failed",
343
+ proposalId: event.proposalId,
344
+ failure: { code: event.error.code, detail: describeStoreError(event.error) },
345
+ };
346
+ default:
347
+ return assertNever(event, "narrowEvent");
348
+ }
349
+ };
350
+ export const recordOf = (envelope) => ({
351
+ treeId: envelope.treeId,
352
+ occurredAt: envelope.occurredAt,
353
+ event: narrowEvent(envelope.event),
354
+ });
355
+ /**
356
+ * The proposal an event is about, when it is about one. Used by the fold rather
357
+ * than stored as a column: a query that needs an index on it is a change with a
358
+ * reason behind it, and duplicating a field into a column is how two copies of
359
+ * the same fact start disagreeing.
360
+ */
361
+ export const proposalIdOf = (event) => {
362
+ switch (event.type) {
363
+ case "change-proposed":
364
+ return event.proposal.proposalId;
365
+ case "change-assessed":
366
+ return event.assessment.proposalId;
367
+ case "repair-requested":
368
+ case "repair-failed":
369
+ return event.refusedProposalId;
370
+ case "assessment-failed":
371
+ case "disposition-decided":
372
+ case "change-applied":
373
+ case "application-failed":
374
+ case "proposal-held":
375
+ case "hold-failed":
376
+ case "hold-confirmed":
377
+ case "hold-discarded":
378
+ case "change-committed":
379
+ case "commit-failed":
380
+ return event.proposalId;
381
+ case "intent-received":
382
+ case "policy-resolved":
383
+ case "interpretation-failed":
384
+ case "intent-not-writable":
385
+ return undefined;
386
+ default:
387
+ return assertNever(event, "proposalIdOf");
388
+ }
389
+ };
390
+ /** The intent an event names directly. Everything else reaches one via its proposal. */
391
+ export const intentIdOf = (event) => {
392
+ switch (event.type) {
393
+ case "intent-received":
394
+ return event.intent.intentId;
395
+ case "policy-resolved":
396
+ case "interpretation-failed":
397
+ case "intent-not-writable":
398
+ return event.intentId;
399
+ case "change-proposed":
400
+ return event.proposal.intentId;
401
+ default:
402
+ return undefined;
403
+ }
404
+ };
405
+ //# sourceMappingURL=event.js.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The record of what the runtime did, and what it can be measured against.
3
+ *
4
+ * An append-only journal of narrated events, the fold that turns them back into
5
+ * episodes, and the calibration that compares what a model claimed against what
6
+ * became of the claim.
7
+ */
8
+ export * from "./calibration.js";
9
+ export * from "./episode.js";
10
+ export * from "./event.js";
11
+ export * from "./journal.js";
12
+ export * from "./memory.js";
13
+ export * from "./retention.js";
14
+ export * from "./sink.js";
15
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The record of what the runtime did, and what it can be measured against.
3
+ *
4
+ * An append-only journal of narrated events, the fold that turns them back into
5
+ * episodes, and the calibration that compares what a model claimed against what
6
+ * became of the claim.
7
+ */
8
+ export * from "./calibration.js";
9
+ export * from "./episode.js";
10
+ export * from "./event.js";
11
+ export * from "./journal.js";
12
+ export * from "./memory.js";
13
+ export * from "./retention.js";
14
+ export * from "./sink.js";
15
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,116 @@
1
+ import type { TreeId } from "../ids.js";
2
+ import { type PageDirection, type PageEnds } from "../paging.js";
3
+ import type { Result } from "../result.js";
4
+ import type { TelemetryRecord } from "./event.js";
5
+ /**
6
+ * Where the narrated runtime goes to be read later.
7
+ *
8
+ * A journal is append-only and answers questions in the order things arrived.
9
+ * It is not the truth about any tree — 0016 already settled that the revision
10
+ * log is — and nothing downstream may reconstruct a tree from it. It is the
11
+ * record of what was proposed, what the Gate decided, and what became of it,
12
+ * including all the changes that never reached the log because they were
13
+ * refused, held, or discarded.
14
+ */
15
+ /**
16
+ * The only way a journal fails. There is no `not-found`: reading a tree nothing
17
+ * has been recorded about is an empty page, not an error, because a journal
18
+ * makes no claim that a tree exists. There is no conflict either — appending an
19
+ * observation cannot collide with another observation.
20
+ */
21
+ export type TelemetryError = {
22
+ readonly code: "unavailable";
23
+ readonly detail: string;
24
+ };
25
+ export declare const describeTelemetryError: (error: TelemetryError) => string;
26
+ /**
27
+ * A record as it comes back out, with the position the journal gave it.
28
+ *
29
+ * `seq` orders records by *arrival*, not by `occurredAt`. Those differ, and the
30
+ * arrival order is the one worth exposing: clocks on two serverless instances
31
+ * disagree by more than the gap between two events in the same request, so a
32
+ * cursor built on a timestamp would skip or repeat rows. `seq` is opaque —
33
+ * increasing, but not a count, not dense, and not comparable across journals.
34
+ */
35
+ export type RecordedTelemetry = TelemetryRecord & {
36
+ readonly seq: number;
37
+ /**
38
+ * When the journal learned of the record, which is not `occurredAt`.
39
+ *
40
+ * Both are here because they answer different questions and only one of them
41
+ * the journal can vouch for. `occurredAt` is what the host said, and a host
42
+ * that sets it wrongly — a skewed serverless clock, a replayed batch — is
43
+ * describing its own timeline. `recordedAt` is stamped on arrival, so it is
44
+ * the only timestamp retention may be measured against: an age a writer can
45
+ * choose is an age a writer can dodge.
46
+ */
47
+ readonly recordedAt: string;
48
+ };
49
+ export type TelemetryReadRequest = {
50
+ /** Absent reads every tree the handle can see, which is the scope rule (0020). */
51
+ readonly treeId?: TreeId;
52
+ /** A cursor from a previous page's `older`/`newer`, passed back unread. */
53
+ readonly cursor?: string;
54
+ /**
55
+ * Default `newer`, which with no cursor is the oldest page. `older` with no
56
+ * cursor is the newest page — the read a reader almost always wants first.
57
+ */
58
+ readonly direction?: PageDirection;
59
+ readonly limit?: number;
60
+ };
61
+ export type TelemetryPage = PageEnds & {
62
+ /**
63
+ * Always ascending by `seq`, whichever end the page was taken from.
64
+ *
65
+ * The direction is a property of *which* records a page contains, never of
66
+ * the order they arrive in. `episodesOf` folds a stream in arrival order, and
67
+ * a page that sometimes came back reversed would make every consumer
68
+ * responsible for knowing which — and silently wrong when it guessed.
69
+ */
70
+ readonly records: readonly RecordedTelemetry[];
71
+ };
72
+ /**
73
+ * Larger than a tree listing's, because these are read to be folded rather than
74
+ * shown: an episode spans a dozen or so records, so a page of 200 is a handful
75
+ * of episodes and a page of 50 would routinely split one across a boundary.
76
+ */
77
+ export declare const DEFAULT_TELEMETRY_LIMIT = 200;
78
+ export declare const MAX_TELEMETRY_LIMIT = 1000;
79
+ export declare const clampTelemetryLimit: (limit: number | undefined) => number;
80
+ /**
81
+ * What a journal is asked to forget, expressed as a position rather than a rule.
82
+ *
83
+ * Every record below `before` goes; nothing else is touched. A journal is not
84
+ * told about ages, policies, or episodes — deciding *what* may be forgotten is
85
+ * `retention.ts`'s job, and it makes that decision by reading the journal
86
+ * through the same paged contract everyone else uses. This half only knows how
87
+ * to drop a prefix, which is why both implementations of it fit in four lines
88
+ * and cannot disagree about anything more interesting than that.
89
+ */
90
+ export type ForgetRequest = {
91
+ readonly before: number;
92
+ };
93
+ export type ForgetOutcome = {
94
+ readonly removed: number;
95
+ };
96
+ /**
97
+ * Three operations, and the asymmetry is deliberate: writes arrive in batches
98
+ * because a request narrates several stages and should pay for one round trip
99
+ * (0024), while reads are paged because a journal only grows.
100
+ *
101
+ * `record` takes a batch rather than a single record so that an implementation
102
+ * can make the batch atomic. Half a request's narration is worse than none of
103
+ * it: an episode missing its disposition reads as a change that was proposed
104
+ * and never judged, which is a fault report rather than a gap.
105
+ *
106
+ * `forget` is the only destructive operation anywhere in Loom's storage, and it
107
+ * is on the journal rather than the store for the reason 0016 gives: telemetry
108
+ * is narrowed from a log that keeps the truth, so forgetting it loses history
109
+ * and never loses a tree.
110
+ */
111
+ export interface TelemetryJournal {
112
+ readonly record: (records: readonly TelemetryRecord[]) => Promise<Result<void, TelemetryError>>;
113
+ readonly read: (request?: TelemetryReadRequest) => Promise<Result<TelemetryPage, TelemetryError>>;
114
+ readonly forget: (request: ForgetRequest) => Promise<Result<ForgetOutcome, TelemetryError>>;
115
+ }
116
+ //# sourceMappingURL=journal.d.ts.map
@@ -0,0 +1,11 @@
1
+ import { clampLimit } from "../paging.js";
2
+ export const describeTelemetryError = (error) => `telemetry is unavailable: ${error.detail}`;
3
+ /**
4
+ * Larger than a tree listing's, because these are read to be folded rather than
5
+ * shown: an episode spans a dozen or so records, so a page of 200 is a handful
6
+ * of episodes and a page of 50 would routinely split one across a boundary.
7
+ */
8
+ export const DEFAULT_TELEMETRY_LIMIT = 200;
9
+ export const MAX_TELEMETRY_LIMIT = 1000;
10
+ export const clampTelemetryLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_TELEMETRY_LIMIT, max: MAX_TELEMETRY_LIMIT });
11
+ //# sourceMappingURL=journal.js.map
@@ -0,0 +1,24 @@
1
+ import { type Clock } from "../runtime/events.js";
2
+ import { type TelemetryJournal } from "./journal.js";
3
+ /**
4
+ * The telemetry journal that keeps its records in the process.
5
+ *
6
+ * It is the implementation the contract is written against, so what it does is
7
+ * what a journal is expected to do.
8
+ */
9
+ /**
10
+ * A journal in memory: the reference implementation of the contract, and the
11
+ * one `pnpm dev` runs on.
12
+ *
13
+ * Like the memory store, it is not a test double. The ordering it promises —
14
+ * arrival order, stable across reads, paged by an opaque cursor — is what a SQL
15
+ * implementation is checked against, and `journal-contract.ts` runs the same
16
+ * suite over both so a disagreement is a test failure rather than a surprise in
17
+ * production.
18
+ *
19
+ * The clock is a parameter for the same reason it is one everywhere else: a
20
+ * `recordedAt` this journal read off the wall clock would make every retention
21
+ * test a race against real time.
22
+ */
23
+ export declare const memoryTelemetryJournal: (clock?: Clock) => TelemetryJournal;
24
+ //# sourceMappingURL=memory.d.ts.map
@@ -0,0 +1,75 @@
1
+ import { cursorPosition, pageEnds } from "../paging.js";
2
+ import { ok } from "../result.js";
3
+ import { systemClock } from "../runtime/events.js";
4
+ import { clampTelemetryLimit, } from "./journal.js";
5
+ /**
6
+ * The telemetry journal that keeps its records in the process.
7
+ *
8
+ * It is the implementation the contract is written against, so what it does is
9
+ * what a journal is expected to do.
10
+ */
11
+ /**
12
+ * A journal in memory: the reference implementation of the contract, and the
13
+ * one `pnpm dev` runs on.
14
+ *
15
+ * Like the memory store, it is not a test double. The ordering it promises —
16
+ * arrival order, stable across reads, paged by an opaque cursor — is what a SQL
17
+ * implementation is checked against, and `journal-contract.ts` runs the same
18
+ * suite over both so a disagreement is a test failure rather than a surprise in
19
+ * production.
20
+ *
21
+ * The clock is a parameter for the same reason it is one everywhere else: a
22
+ * `recordedAt` this journal read off the wall clock would make every retention
23
+ * test a race against real time.
24
+ */
25
+ export const memoryTelemetryJournal = (clock = systemClock) => {
26
+ let records = [];
27
+ let nextSeq = 1;
28
+ const positioned = (record) => ({
29
+ ...record,
30
+ seq: nextSeq++,
31
+ recordedAt: clock.now(),
32
+ });
33
+ return {
34
+ record: (batch) => {
35
+ /**
36
+ * Appended in one statement, so a reader can never see half a request's
37
+ * narration — the atomicity the contract asks of every implementation.
38
+ */
39
+ records.push(...batch.map(positioned));
40
+ return Promise.resolve(ok(undefined));
41
+ },
42
+ read: (request) => {
43
+ const limit = clampTelemetryLimit(request?.limit);
44
+ const from = cursorPosition(request?.cursor);
45
+ const direction = request?.direction ?? "newer";
46
+ const matching = records.filter((record) => (request?.treeId === undefined || record.treeId === request.treeId) &&
47
+ (from === undefined || (direction === "older" ? record.seq < from : record.seq > from)));
48
+ /**
49
+ * `older` takes the page from the far end, which is a slice rather than a
50
+ * reverse: the records that come back are still in arrival order, because
51
+ * the contract says a page's order never depends on which end it came from.
52
+ */
53
+ const page = direction === "older" ? matching.slice(-limit) : matching.slice(0, limit);
54
+ return Promise.resolve(ok({
55
+ records: page,
56
+ ...pageEnds(page.map((record) => record.seq), direction, {
57
+ beyond: matching.length > page.length,
58
+ resumed: from !== undefined,
59
+ }),
60
+ }));
61
+ },
62
+ /**
63
+ * `nextSeq` is deliberately not rewound. A forgotten position must never be
64
+ * handed out again: a cursor a reader is holding across a prune would
65
+ * otherwise resume in the middle of records it has already seen.
66
+ */
67
+ forget: ({ before }) => {
68
+ const kept = records.filter((record) => record.seq >= before);
69
+ const removed = records.length - kept.length;
70
+ records = kept;
71
+ return Promise.resolve(ok({ removed }));
72
+ },
73
+ };
74
+ };
75
+ //# sourceMappingURL=memory.js.map