@czap/core 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 (372) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +19 -0
  3. package/dist/addressed-digest.d.ts +15 -0
  4. package/dist/addressed-digest.d.ts.map +1 -0
  5. package/dist/addressed-digest.js +35 -0
  6. package/dist/addressed-digest.js.map +1 -0
  7. package/dist/animation.d.ts +46 -0
  8. package/dist/animation.d.ts.map +1 -0
  9. package/dist/animation.js +70 -0
  10. package/dist/animation.js.map +1 -0
  11. package/dist/assembly.d.ts +25 -0
  12. package/dist/assembly.d.ts.map +1 -0
  13. package/dist/assembly.js +58 -0
  14. package/dist/assembly.js.map +1 -0
  15. package/dist/av-bridge.d.ts +74 -0
  16. package/dist/av-bridge.d.ts.map +1 -0
  17. package/dist/av-bridge.js +107 -0
  18. package/dist/av-bridge.js.map +1 -0
  19. package/dist/av-renderer.d.ts +56 -0
  20. package/dist/av-renderer.d.ts.map +1 -0
  21. package/dist/av-renderer.js +65 -0
  22. package/dist/av-renderer.js.map +1 -0
  23. package/dist/blend.d.ts +61 -0
  24. package/dist/blend.d.ts.map +1 -0
  25. package/dist/blend.js +100 -0
  26. package/dist/blend.js.map +1 -0
  27. package/dist/boundary.d.ts +154 -0
  28. package/dist/boundary.d.ts.map +1 -0
  29. package/dist/boundary.js +269 -0
  30. package/dist/boundary.js.map +1 -0
  31. package/dist/brands.d.ts +63 -0
  32. package/dist/brands.d.ts.map +1 -0
  33. package/dist/brands.js +31 -0
  34. package/dist/brands.js.map +1 -0
  35. package/dist/caps.d.ts +49 -0
  36. package/dist/caps.d.ts.map +1 -0
  37. package/dist/caps.js +73 -0
  38. package/dist/caps.js.map +1 -0
  39. package/dist/capsule.d.ts +77 -0
  40. package/dist/capsule.d.ts.map +1 -0
  41. package/dist/capsule.js +18 -0
  42. package/dist/capsule.js.map +1 -0
  43. package/dist/capsules/boundary-evaluate.d.ts +28 -0
  44. package/dist/capsules/boundary-evaluate.d.ts.map +1 -0
  45. package/dist/capsules/boundary-evaluate.js +117 -0
  46. package/dist/capsules/boundary-evaluate.js.map +1 -0
  47. package/dist/capsules/canonical-cbor.d.ts +13 -0
  48. package/dist/capsules/canonical-cbor.d.ts.map +1 -0
  49. package/dist/capsules/canonical-cbor.js +60 -0
  50. package/dist/capsules/canonical-cbor.js.map +1 -0
  51. package/dist/capsules/token-buffer.d.ts +24 -0
  52. package/dist/capsules/token-buffer.d.ts.map +1 -0
  53. package/dist/capsules/token-buffer.js +53 -0
  54. package/dist/capsules/token-buffer.js.map +1 -0
  55. package/dist/capture.d.ts +40 -0
  56. package/dist/capture.d.ts.map +1 -0
  57. package/dist/capture.js +10 -0
  58. package/dist/capture.js.map +1 -0
  59. package/dist/cbor.d.ts +33 -0
  60. package/dist/cbor.d.ts.map +1 -0
  61. package/dist/cbor.js +179 -0
  62. package/dist/cbor.js.map +1 -0
  63. package/dist/cell.d.ts +53 -0
  64. package/dist/cell.d.ts.map +1 -0
  65. package/dist/cell.js +83 -0
  66. package/dist/cell.js.map +1 -0
  67. package/dist/codec.d.ts +30 -0
  68. package/dist/codec.d.ts.map +1 -0
  69. package/dist/codec.js +25 -0
  70. package/dist/codec.js.map +1 -0
  71. package/dist/component.d.ts +52 -0
  72. package/dist/component.d.ts.map +1 -0
  73. package/dist/component.js +44 -0
  74. package/dist/component.js.map +1 -0
  75. package/dist/composable.d.ts +76 -0
  76. package/dist/composable.d.ts.map +1 -0
  77. package/dist/composable.js +221 -0
  78. package/dist/composable.js.map +1 -0
  79. package/dist/compositor-pool.d.ts +74 -0
  80. package/dist/compositor-pool.d.ts.map +1 -0
  81. package/dist/compositor-pool.js +119 -0
  82. package/dist/compositor-pool.js.map +1 -0
  83. package/dist/compositor.d.ts +90 -0
  84. package/dist/compositor.d.ts.map +1 -0
  85. package/dist/compositor.js +278 -0
  86. package/dist/compositor.js.map +1 -0
  87. package/dist/config.d.ts +72 -0
  88. package/dist/config.d.ts.map +1 -0
  89. package/dist/config.js +97 -0
  90. package/dist/config.js.map +1 -0
  91. package/dist/dag.d.ts +251 -0
  92. package/dist/dag.d.ts.map +1 -0
  93. package/dist/dag.js +450 -0
  94. package/dist/dag.js.map +1 -0
  95. package/dist/defaults.d.ts +45 -0
  96. package/dist/defaults.d.ts.map +1 -0
  97. package/dist/defaults.js +45 -0
  98. package/dist/defaults.js.map +1 -0
  99. package/dist/derived.d.ts +34 -0
  100. package/dist/derived.d.ts.map +1 -0
  101. package/dist/derived.js +101 -0
  102. package/dist/derived.js.map +1 -0
  103. package/dist/diagnostics.d.ts +77 -0
  104. package/dist/diagnostics.d.ts.map +1 -0
  105. package/dist/diagnostics.js +122 -0
  106. package/dist/diagnostics.js.map +1 -0
  107. package/dist/dirty.d.ts +55 -0
  108. package/dist/dirty.d.ts.map +1 -0
  109. package/dist/dirty.js +80 -0
  110. package/dist/dirty.js.map +1 -0
  111. package/dist/easing.d.ts +55 -0
  112. package/dist/easing.d.ts.map +1 -0
  113. package/dist/easing.js +291 -0
  114. package/dist/easing.js.map +1 -0
  115. package/dist/ecs.d.ts +105 -0
  116. package/dist/ecs.d.ts.map +1 -0
  117. package/dist/ecs.js +245 -0
  118. package/dist/ecs.js.map +1 -0
  119. package/dist/fnv.d.ts +14 -0
  120. package/dist/fnv.d.ts.map +1 -0
  121. package/dist/fnv.js +28 -0
  122. package/dist/fnv.js.map +1 -0
  123. package/dist/frame-budget.d.ts +73 -0
  124. package/dist/frame-budget.d.ts.map +1 -0
  125. package/dist/frame-budget.js +114 -0
  126. package/dist/frame-budget.js.map +1 -0
  127. package/dist/gen-frame.d.ts +102 -0
  128. package/dist/gen-frame.d.ts.map +1 -0
  129. package/dist/gen-frame.js +121 -0
  130. package/dist/gen-frame.js.map +1 -0
  131. package/dist/harness/arbitrary-from-schema.d.ts +28 -0
  132. package/dist/harness/arbitrary-from-schema.d.ts.map +1 -0
  133. package/dist/harness/arbitrary-from-schema.js +262 -0
  134. package/dist/harness/arbitrary-from-schema.js.map +1 -0
  135. package/dist/harness/cached-projection.d.ts +19 -0
  136. package/dist/harness/cached-projection.d.ts.map +1 -0
  137. package/dist/harness/cached-projection.js +39 -0
  138. package/dist/harness/cached-projection.js.map +1 -0
  139. package/dist/harness/index.d.ts +16 -0
  140. package/dist/harness/index.d.ts.map +1 -0
  141. package/dist/harness/index.js +15 -0
  142. package/dist/harness/index.js.map +1 -0
  143. package/dist/harness/policy-gate.d.ts +18 -0
  144. package/dist/harness/policy-gate.d.ts.map +1 -0
  145. package/dist/harness/policy-gate.js +46 -0
  146. package/dist/harness/policy-gate.js.map +1 -0
  147. package/dist/harness/pure-transform.d.ts +42 -0
  148. package/dist/harness/pure-transform.d.ts.map +1 -0
  149. package/dist/harness/pure-transform.js +76 -0
  150. package/dist/harness/pure-transform.js.map +1 -0
  151. package/dist/harness/receipted-mutation.d.ts +23 -0
  152. package/dist/harness/receipted-mutation.d.ts.map +1 -0
  153. package/dist/harness/receipted-mutation.js +52 -0
  154. package/dist/harness/receipted-mutation.js.map +1 -0
  155. package/dist/harness/scene-composition.d.ts +19 -0
  156. package/dist/harness/scene-composition.d.ts.map +1 -0
  157. package/dist/harness/scene-composition.js +47 -0
  158. package/dist/harness/scene-composition.js.map +1 -0
  159. package/dist/harness/site-adapter.d.ts +18 -0
  160. package/dist/harness/site-adapter.d.ts.map +1 -0
  161. package/dist/harness/site-adapter.js +38 -0
  162. package/dist/harness/site-adapter.js.map +1 -0
  163. package/dist/harness/state-machine.d.ts +19 -0
  164. package/dist/harness/state-machine.d.ts.map +1 -0
  165. package/dist/harness/state-machine.js +44 -0
  166. package/dist/harness/state-machine.js.map +1 -0
  167. package/dist/hlc.d.ts +99 -0
  168. package/dist/hlc.d.ts.map +1 -0
  169. package/dist/hlc.js +219 -0
  170. package/dist/hlc.js.map +1 -0
  171. package/dist/index.d.ts +104 -0
  172. package/dist/index.d.ts.map +1 -0
  173. package/dist/index.js +137 -0
  174. package/dist/index.js.map +1 -0
  175. package/dist/interpolate.d.ts +14 -0
  176. package/dist/interpolate.d.ts.map +1 -0
  177. package/dist/interpolate.js +31 -0
  178. package/dist/interpolate.js.map +1 -0
  179. package/dist/live-cell.d.ts +46 -0
  180. package/dist/live-cell.d.ts.map +1 -0
  181. package/dist/live-cell.js +154 -0
  182. package/dist/live-cell.js.map +1 -0
  183. package/dist/op.d.ts +58 -0
  184. package/dist/op.d.ts.map +1 -0
  185. package/dist/op.js +171 -0
  186. package/dist/op.js.map +1 -0
  187. package/dist/plan.d.ts +195 -0
  188. package/dist/plan.d.ts.map +1 -0
  189. package/dist/plan.js +211 -0
  190. package/dist/plan.js.map +1 -0
  191. package/dist/protocol.d.ts +33 -0
  192. package/dist/protocol.d.ts.map +1 -0
  193. package/dist/protocol.js +10 -0
  194. package/dist/protocol.js.map +1 -0
  195. package/dist/quantizer-types.d.ts +28 -0
  196. package/dist/quantizer-types.d.ts.map +1 -0
  197. package/dist/quantizer-types.js +9 -0
  198. package/dist/quantizer-types.js.map +1 -0
  199. package/dist/receipt.d.ts +294 -0
  200. package/dist/receipt.d.ts.map +1 -0
  201. package/dist/receipt.js +352 -0
  202. package/dist/receipt.js.map +1 -0
  203. package/dist/runtime-coordinator.d.ts +75 -0
  204. package/dist/runtime-coordinator.d.ts.map +1 -0
  205. package/dist/runtime-coordinator.js +149 -0
  206. package/dist/runtime-coordinator.js.map +1 -0
  207. package/dist/scheduler.d.ts +58 -0
  208. package/dist/scheduler.d.ts.map +1 -0
  209. package/dist/scheduler.js +109 -0
  210. package/dist/scheduler.js.map +1 -0
  211. package/dist/ship-capsule.d.ts +54 -0
  212. package/dist/ship-capsule.d.ts.map +1 -0
  213. package/dist/ship-capsule.js +142 -0
  214. package/dist/ship-capsule.js.map +1 -0
  215. package/dist/ship-manifest.d.ts +45 -0
  216. package/dist/ship-manifest.d.ts.map +1 -0
  217. package/dist/ship-manifest.js +175 -0
  218. package/dist/ship-manifest.js.map +1 -0
  219. package/dist/signal.d.ts +149 -0
  220. package/dist/signal.d.ts.map +1 -0
  221. package/dist/signal.js +277 -0
  222. package/dist/signal.js.map +1 -0
  223. package/dist/speculative.d.ts +67 -0
  224. package/dist/speculative.d.ts.map +1 -0
  225. package/dist/speculative.js +139 -0
  226. package/dist/speculative.js.map +1 -0
  227. package/dist/store.d.ts +39 -0
  228. package/dist/store.d.ts.map +1 -0
  229. package/dist/store.js +42 -0
  230. package/dist/store.js.map +1 -0
  231. package/dist/style.d.ts +119 -0
  232. package/dist/style.d.ts.map +1 -0
  233. package/dist/style.js +168 -0
  234. package/dist/style.js.map +1 -0
  235. package/dist/testing.d.ts +14 -0
  236. package/dist/testing.d.ts.map +1 -0
  237. package/dist/testing.js +14 -0
  238. package/dist/testing.js.map +1 -0
  239. package/dist/theme.d.ts +78 -0
  240. package/dist/theme.d.ts.map +1 -0
  241. package/dist/theme.js +109 -0
  242. package/dist/theme.js.map +1 -0
  243. package/dist/timeline.d.ts +45 -0
  244. package/dist/timeline.d.ts.map +1 -0
  245. package/dist/timeline.js +101 -0
  246. package/dist/timeline.js.map +1 -0
  247. package/dist/token-buffer.d.ts +43 -0
  248. package/dist/token-buffer.d.ts.map +1 -0
  249. package/dist/token-buffer.js +112 -0
  250. package/dist/token-buffer.js.map +1 -0
  251. package/dist/token.d.ts +107 -0
  252. package/dist/token.d.ts.map +1 -0
  253. package/dist/token.js +143 -0
  254. package/dist/token.js.map +1 -0
  255. package/dist/tuple.d.ts +16 -0
  256. package/dist/tuple.d.ts.map +1 -0
  257. package/dist/tuple.js +16 -0
  258. package/dist/tuple.js.map +1 -0
  259. package/dist/type-utils.d.ts +41 -0
  260. package/dist/type-utils.d.ts.map +1 -0
  261. package/dist/type-utils.js +10 -0
  262. package/dist/type-utils.js.map +1 -0
  263. package/dist/typed-ref.d.ts +50 -0
  264. package/dist/typed-ref.d.ts.map +1 -0
  265. package/dist/typed-ref.js +59 -0
  266. package/dist/typed-ref.js.map +1 -0
  267. package/dist/ui-quality.d.ts +50 -0
  268. package/dist/ui-quality.d.ts.map +1 -0
  269. package/dist/ui-quality.js +64 -0
  270. package/dist/ui-quality.js.map +1 -0
  271. package/dist/validation-error.d.ts +25 -0
  272. package/dist/validation-error.d.ts.map +1 -0
  273. package/dist/validation-error.js +32 -0
  274. package/dist/validation-error.js.map +1 -0
  275. package/dist/vector-clock.d.ts +46 -0
  276. package/dist/vector-clock.d.ts.map +1 -0
  277. package/dist/vector-clock.js +91 -0
  278. package/dist/vector-clock.js.map +1 -0
  279. package/dist/video.d.ts +62 -0
  280. package/dist/video.d.ts.map +1 -0
  281. package/dist/video.js +59 -0
  282. package/dist/video.js.map +1 -0
  283. package/dist/wasm-dispatch.d.ts +52 -0
  284. package/dist/wasm-dispatch.d.ts.map +1 -0
  285. package/dist/wasm-dispatch.js +204 -0
  286. package/dist/wasm-dispatch.js.map +1 -0
  287. package/dist/wasm-fallback.d.ts +19 -0
  288. package/dist/wasm-fallback.d.ts.map +1 -0
  289. package/dist/wasm-fallback.js +93 -0
  290. package/dist/wasm-fallback.js.map +1 -0
  291. package/dist/wire.d.ts +49 -0
  292. package/dist/wire.d.ts.map +1 -0
  293. package/dist/wire.js +201 -0
  294. package/dist/wire.js.map +1 -0
  295. package/dist/zap.d.ts +42 -0
  296. package/dist/zap.d.ts.map +1 -0
  297. package/dist/zap.js +172 -0
  298. package/dist/zap.js.map +1 -0
  299. package/package.json +71 -0
  300. package/src/addressed-digest.ts +48 -0
  301. package/src/animation.ts +103 -0
  302. package/src/assembly.ts +76 -0
  303. package/src/av-bridge.ts +161 -0
  304. package/src/av-renderer.ts +118 -0
  305. package/src/blend.ts +135 -0
  306. package/src/boundary.ts +363 -0
  307. package/src/brands.ts +86 -0
  308. package/src/caps.ts +100 -0
  309. package/src/capsule.ts +95 -0
  310. package/src/capsules/boundary-evaluate.ts +128 -0
  311. package/src/capsules/canonical-cbor.ts +60 -0
  312. package/src/capsules/token-buffer.ts +57 -0
  313. package/src/capture.ts +48 -0
  314. package/src/cbor.ts +199 -0
  315. package/src/cell.ts +130 -0
  316. package/src/codec.ts +39 -0
  317. package/src/component.ts +102 -0
  318. package/src/composable.ts +328 -0
  319. package/src/compositor-pool.ts +162 -0
  320. package/src/compositor.ts +387 -0
  321. package/src/config.ts +157 -0
  322. package/src/dag.ts +527 -0
  323. package/src/defaults.ts +60 -0
  324. package/src/derived.ts +164 -0
  325. package/src/diagnostics.ts +186 -0
  326. package/src/dirty.ts +101 -0
  327. package/src/easing.ts +334 -0
  328. package/src/ecs.ts +382 -0
  329. package/src/fnv.ts +31 -0
  330. package/src/frame-budget.ts +149 -0
  331. package/src/gen-frame.ts +229 -0
  332. package/src/harness/arbitrary-from-schema.ts +270 -0
  333. package/src/harness/cached-projection.ts +46 -0
  334. package/src/harness/index.ts +16 -0
  335. package/src/harness/policy-gate.ts +51 -0
  336. package/src/harness/pure-transform.ts +121 -0
  337. package/src/harness/receipted-mutation.ts +59 -0
  338. package/src/harness/scene-composition.ts +54 -0
  339. package/src/harness/site-adapter.ts +43 -0
  340. package/src/harness/state-machine.ts +49 -0
  341. package/src/hlc.ts +238 -0
  342. package/src/index.ts +274 -0
  343. package/src/interpolate.ts +37 -0
  344. package/src/live-cell.ts +199 -0
  345. package/src/op.ts +233 -0
  346. package/src/plan.ts +317 -0
  347. package/src/protocol.ts +49 -0
  348. package/src/quantizer-types.ts +29 -0
  349. package/src/receipt.ts +444 -0
  350. package/src/runtime-coordinator.ts +230 -0
  351. package/src/scheduler.ts +161 -0
  352. package/src/ship-capsule.ts +191 -0
  353. package/src/signal.ts +345 -0
  354. package/src/speculative.ts +186 -0
  355. package/src/store.ts +77 -0
  356. package/src/style.ts +249 -0
  357. package/src/testing.ts +14 -0
  358. package/src/theme.ts +153 -0
  359. package/src/timeline.ts +146 -0
  360. package/src/token-buffer.ts +151 -0
  361. package/src/token.ts +197 -0
  362. package/src/tuple.ts +19 -0
  363. package/src/type-utils.ts +48 -0
  364. package/src/typed-ref.ts +79 -0
  365. package/src/ui-quality.ts +105 -0
  366. package/src/validation-error.ts +34 -0
  367. package/src/vector-clock.ts +111 -0
  368. package/src/video.ts +106 -0
  369. package/src/wasm-dispatch.ts +300 -0
  370. package/src/wasm-fallback.ts +102 -0
  371. package/src/wire.ts +274 -0
  372. package/src/zap.ts +241 -0
package/dist/plan.js ADDED
@@ -0,0 +1,211 @@
1
+ /**
2
+ * Plan -- plan IR builder for universal execution DAG.
3
+ *
4
+ * @module
5
+ */
6
+ class PlanBuilderImpl {
7
+ planName;
8
+ steps = [];
9
+ edges = [];
10
+ constructor(planName) {
11
+ this.planName = planName;
12
+ }
13
+ step(name, opType, metadata) {
14
+ const id = `step-${this.steps.length + 1}`;
15
+ this.steps.push({ id, name, opType, metadata });
16
+ return this;
17
+ }
18
+ seq(fromId, toId) {
19
+ this.edges.push({ from: fromId, to: toId, type: 'seq' });
20
+ return this;
21
+ }
22
+ par(fromId, toId) {
23
+ this.edges.push({ from: fromId, to: toId, type: 'par' });
24
+ return this;
25
+ }
26
+ choice(fromId, thenId, elseId) {
27
+ this.edges.push({ from: fromId, to: thenId, type: 'choice_then' });
28
+ this.edges.push({ from: fromId, to: elseId, type: 'choice_else' });
29
+ return this;
30
+ }
31
+ build() {
32
+ return {
33
+ name: this.planName,
34
+ steps: [...this.steps],
35
+ edges: [...this.edges],
36
+ };
37
+ }
38
+ }
39
+ /**
40
+ * Create a new PlanBuilder with the given plan name.
41
+ *
42
+ * Returns a fluent builder that supports chaining `.step()`, `.seq()`,
43
+ * `.par()`, and `.choice()` calls. Call `.build()` to produce the PlanIR.
44
+ *
45
+ * @example
46
+ * ```ts
47
+ * const plan = Plan.make('my-pipeline')
48
+ * .step('fetch', { type: 'effect' })
49
+ * .step('transform', { type: 'pure' })
50
+ * .seq('step-1', 'step-2')
51
+ * .build();
52
+ * // plan.name === 'my-pipeline'
53
+ * // plan.steps.length === 2
54
+ * // plan.edges.length === 1
55
+ * ```
56
+ */
57
+ function _make(name) {
58
+ return new PlanBuilderImpl(name);
59
+ }
60
+ function hasCycle(planIR) {
61
+ const visited = new Set();
62
+ const recStack = new Set();
63
+ const adjList = new Map();
64
+ for (const step of planIR.steps) {
65
+ adjList.set(step.id, []);
66
+ }
67
+ for (const edge of planIR.edges) {
68
+ adjList.get(edge.from)?.push(edge.to);
69
+ }
70
+ function dfs(node) {
71
+ visited.add(node);
72
+ recStack.add(node);
73
+ for (const neighbor of adjList.get(node) ?? []) {
74
+ if (!visited.has(neighbor)) {
75
+ if (dfs(neighbor))
76
+ return true;
77
+ }
78
+ else if (recStack.has(neighbor)) {
79
+ return true;
80
+ }
81
+ }
82
+ recStack.delete(node);
83
+ return false;
84
+ }
85
+ for (const step of planIR.steps) {
86
+ if (!visited.has(step.id) && dfs(step.id))
87
+ return true;
88
+ }
89
+ return false;
90
+ }
91
+ /**
92
+ * Validate a PlanIR for structural correctness.
93
+ *
94
+ * Checks that all edges reference existing steps and that the graph is acyclic.
95
+ * Returns `{ ok: true, plan }` on success or `{ ok: false, errors }` with
96
+ * detailed validation errors.
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * const plan = Plan.make('test').step('a', { type: 'noop' }).build();
101
+ * const result = Plan.validate(plan);
102
+ * // result.ok === true
103
+ * // result.plan === plan
104
+ * ```
105
+ */
106
+ function _validate(planIR) {
107
+ const errors = [];
108
+ const stepIds = new Set(planIR.steps.map((s) => s.id));
109
+ for (const edge of planIR.edges) {
110
+ if (!stepIds.has(edge.from)) {
111
+ errors.push({
112
+ type: 'missing_step',
113
+ message: `Edge references unknown step: ${edge.from}`,
114
+ stepIds: [edge.from],
115
+ });
116
+ }
117
+ if (!stepIds.has(edge.to)) {
118
+ errors.push({
119
+ type: 'missing_step',
120
+ message: `Edge references unknown step: ${edge.to}`,
121
+ stepIds: [edge.to],
122
+ });
123
+ }
124
+ }
125
+ if (hasCycle(planIR)) {
126
+ errors.push({ type: 'cycle', message: 'Plan contains a cycle' });
127
+ }
128
+ return errors.length === 0 ? { ok: true, plan: planIR } : { ok: false, errors };
129
+ }
130
+ /**
131
+ * Topologically sort the steps of a PlanIR using Kahn's algorithm.
132
+ *
133
+ * Returns `{ sorted }` on success. If a cycle exists, returns
134
+ * `{ sorted, cycle }` where `cycle` lists the step IDs involved.
135
+ *
136
+ * @example
137
+ * ```ts
138
+ * const plan = Plan.make('pipeline')
139
+ * .step('a', { type: 'pure' })
140
+ * .step('b', { type: 'pure' })
141
+ * .seq('step-1', 'step-2')
142
+ * .build();
143
+ * const result = Plan.topoSort(plan);
144
+ * // result.sorted === ['step-1', 'step-2']
145
+ * ```
146
+ */
147
+ function _topoSort(planIR) {
148
+ const adjList = new Map();
149
+ const inDegree = new Map();
150
+ for (const step of planIR.steps) {
151
+ adjList.set(step.id, []);
152
+ inDegree.set(step.id, 0);
153
+ }
154
+ for (const edge of planIR.edges) {
155
+ adjList.get(edge.from)?.push(edge.to);
156
+ inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
157
+ }
158
+ const queue = [];
159
+ const result = [];
160
+ for (const [id, degree] of inDegree) {
161
+ if (degree === 0)
162
+ queue.push(id);
163
+ }
164
+ while (queue.length > 0) {
165
+ const current = queue.shift();
166
+ result.push(current);
167
+ for (const neighbor of adjList.get(current) ?? []) {
168
+ const newDegree = inDegree.get(neighbor) - 1;
169
+ inDegree.set(neighbor, newDegree);
170
+ if (newDegree === 0)
171
+ queue.push(neighbor);
172
+ }
173
+ }
174
+ if (result.length !== planIR.steps.length) {
175
+ const resultSet = new Set(result);
176
+ const cycleNodes = planIR.steps.filter((s) => !resultSet.has(s.id)).map((s) => s.id);
177
+ return { sorted: result, cycle: cycleNodes };
178
+ }
179
+ return { sorted: result };
180
+ }
181
+ /**
182
+ * Plan namespace -- plan IR builder for universal execution DAG.
183
+ *
184
+ * Build, validate, and topologically sort execution plans. Plans model
185
+ * computation graphs with sequential, parallel, and conditional edges.
186
+ *
187
+ * @example
188
+ * ```ts
189
+ * import { Plan } from '@czap/core';
190
+ *
191
+ * const plan = Plan.make('render-pipeline')
192
+ * .step('load', { type: 'effect' })
193
+ * .step('compile', { type: 'pure' })
194
+ * .step('emit', { type: 'effect' })
195
+ * .seq('step-1', 'step-2')
196
+ * .seq('step-2', 'step-3')
197
+ * .build();
198
+ * const valid = Plan.validate(plan);
199
+ * const order = Plan.topoSort(plan);
200
+ * // order.sorted === ['step-1', 'step-2', 'step-3']
201
+ * ```
202
+ */
203
+ export const Plan = {
204
+ /** Start a new fluent {@link Plan.Builder} with the given display name. */
205
+ make: _make,
206
+ /** Check that every edge references a known step and that the graph is acyclic. */
207
+ validate: _validate,
208
+ /** Kahn's-algorithm topological sort; surfaces cycle participants if the plan is not a DAG. */
209
+ topoSort: _topoSort,
210
+ };
211
+ //# sourceMappingURL=plan.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plan.js","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Protocol types -- CellEnvelope, CellKind, CellMeta.
3
+ *
4
+ * These types form the wire-level protocol for cells in the czap system.
5
+ * Every cell has a kind, content address, metadata, and value.
6
+ *
7
+ * @module
8
+ */
9
+ import type { ContentAddress, HLC } from './brands.js';
10
+ /**
11
+ * Discriminator tagging what a {@link CellEnvelope} carries — a boundary, a
12
+ * discrete state, a target output (CSS/GLSL/WGSL/ARIA/AI), or one of the
13
+ * other reactive shapes produced along the pipeline.
14
+ */
15
+ export type CellKind = 'boundary' | 'state' | 'output' | 'signal' | 'transition' | 'timeline' | 'compositor' | 'blend' | 'css' | 'glsl' | 'wgsl' | 'aria' | 'ai';
16
+ /** Protocol metadata attached to every {@link CellEnvelope}: HLC timestamps + monotonic version counter. */
17
+ export interface CellMeta {
18
+ readonly created: HLC;
19
+ readonly updated: HLC;
20
+ readonly version: number;
21
+ }
22
+ /**
23
+ * Wire-level envelope for a cell value: tagged by {@link CellKind}, identified
24
+ * by its content address, stamped with {@link CellMeta}, carrying the typed
25
+ * payload in `value`.
26
+ */
27
+ export interface CellEnvelope<K extends CellKind = CellKind, T = unknown> {
28
+ readonly kind: K;
29
+ readonly id: ContentAddress;
30
+ readonly meta: CellMeta;
31
+ readonly value: T;
32
+ }
33
+ //# sourceMappingURL=protocol.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,OAAO,GACP,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,GACN,IAAI,CAAC;AAET,4GAA4G;AAC5G,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,CAAC,GAAG,OAAO;IACtE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Protocol types -- CellEnvelope, CellKind, CellMeta.
3
+ *
4
+ * These types form the wire-level protocol for cells in the czap system.
5
+ * Every cell has a kind, content address, metadata, and value.
6
+ *
7
+ * @module
8
+ */
9
+ export {};
10
+ //# sourceMappingURL=protocol.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Quantizer interface -- the base contract for quantizer implementations.
3
+ *
4
+ * The canonical implementation lives in `@czap/quantizer` (`Q.from()` builder API).
5
+ *
6
+ * @module
7
+ */
8
+ import type { Effect, Stream } from 'effect';
9
+ import type { Boundary } from './boundary.js';
10
+ import type { StateUnion, BoundaryCrossing } from './type-utils.js';
11
+ /**
12
+ * Quantizer contract — the live evaluator that binds a {@link Boundary} to a signal source.
13
+ *
14
+ * A quantizer holds a boundary definition plus the reactive machinery to observe
15
+ * its current state and emit crossings when the underlying signal moves between
16
+ * bands. The concrete implementation is produced by `@czap/quantizer`'s `Q.from()`
17
+ * builder; consumers interact only via this structural interface.
18
+ */
19
+ export interface Quantizer<B extends Boundary.Shape = Boundary.Shape> {
20
+ readonly _tag: 'Quantizer';
21
+ readonly boundary: B;
22
+ readonly state: Effect.Effect<StateUnion<B>>;
23
+ /** Synchronous state accessor for hot paths (avoids Effect overhead). */
24
+ readonly stateSync?: () => StateUnion<B>;
25
+ readonly changes: Stream.Stream<BoundaryCrossing<StateUnion<B> & string>>;
26
+ evaluate(value: number): StateUnion<B>;
27
+ }
28
+ //# sourceMappingURL=quantizer-types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"quantizer-types.d.ts","sourceRoot":"","sources":["../src/quantizer-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK;IAClE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;CACxC"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Quantizer interface -- the base contract for quantizer implementations.
3
+ *
4
+ * The canonical implementation lives in `@czap/quantizer` (`Q.from()` builder API).
5
+ *
6
+ * @module
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=quantizer-types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"quantizer-types.js","sourceRoot":"","sources":["../src/quantizer-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
@@ -0,0 +1,294 @@
1
+ /**
2
+ * Receipt -- chain validation and envelope construction.
3
+ *
4
+ * Salvaged from `@kit/core`.
5
+ *
6
+ * @module
7
+ */
8
+ import { Effect } from 'effect';
9
+ import type { HLC } from './brands.js';
10
+ import { type TypedRef } from './typed-ref.js';
11
+ /** The logical entity a receipt describes: an effect, a run, an artifact, or an intent. */
12
+ export interface ReceiptSubject {
13
+ readonly type: 'effect' | 'run' | 'artifact' | 'intent';
14
+ readonly id: string;
15
+ }
16
+ /**
17
+ * Single link in a receipt chain: timestamped, content-addressed, and linked
18
+ * to its predecessor(s). Merge envelopes carry an array of `previous` hashes;
19
+ * optionally MAC-signed via `Receipt.macEnvelope`.
20
+ */
21
+ export interface ReceiptEnvelope {
22
+ readonly kind: string;
23
+ readonly timestamp: HLC;
24
+ readonly subject: ReceiptSubject;
25
+ readonly payload: TypedRef.Shape;
26
+ readonly hash: string;
27
+ readonly previous: string | readonly string[];
28
+ readonly signature?: string;
29
+ }
30
+ /** Structured failure returned by `Receipt.validateChainDetailed`. */
31
+ export type ChainValidationError = {
32
+ readonly type: 'not_genesis';
33
+ readonly index: 0;
34
+ } | {
35
+ readonly type: 'hash_mismatch';
36
+ readonly index: number;
37
+ readonly computed: string;
38
+ readonly stored: string;
39
+ } | {
40
+ readonly type: 'chain_break';
41
+ readonly index: number;
42
+ readonly expected: string;
43
+ readonly actual: string;
44
+ } | {
45
+ readonly type: 'hlc_not_increasing';
46
+ readonly index: number;
47
+ };
48
+ /** Sentinel `previous` value marking the root of a receipt chain. */
49
+ export declare const GENESIS: string;
50
+ /**
51
+ * Compute the content hash of a receipt envelope.
52
+ *
53
+ * Normalizes the `previous` field (sorts array form), canonicalizes the
54
+ * payload, and hashes with SHA-256 via TypedRef.
55
+ *
56
+ * @example
57
+ * ```ts
58
+ * import { Effect } from 'effect';
59
+ *
60
+ * const hash = yield* Receipt.hashEnvelope(envelope);
61
+ * // hash === envelope.hash (if envelope is valid)
62
+ * ```
63
+ */
64
+ export declare const hashEnvelope: (envelope: ReceiptEnvelope) => Effect.Effect<string>;
65
+ /**
66
+ * Create a new receipt envelope with an auto-computed content hash.
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * const envelope = yield* Receipt.createEnvelope(
71
+ * 'state-change',
72
+ * { type: 'effect', id: 'actor-1' },
73
+ * { _tag: 'TypedRef', mediaType: 'application/json', data: { key: 'value' } },
74
+ * hlcTimestamp,
75
+ * Receipt.GENESIS,
76
+ * );
77
+ * // envelope.hash is the computed SHA-256 content address
78
+ * ```
79
+ */
80
+ export declare const createEnvelope: (kind: string, subject: ReceiptSubject, payload: TypedRef.Shape, timestamp: HLC, previousHash: string | readonly string[]) => Effect.Effect<ReceiptEnvelope>;
81
+ /**
82
+ * Build a linear chain of receipt envelopes from an array of entries.
83
+ *
84
+ * Each envelope's `previous` points to the prior envelope's hash,
85
+ * starting from GENESIS.
86
+ *
87
+ * @example
88
+ * ```ts
89
+ * const chain = yield* Receipt.buildChain([
90
+ * { kind: 'init', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts1 },
91
+ * { kind: 'update', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts2 },
92
+ * ]);
93
+ * // chain.length === 2
94
+ * // chain[1].previous === chain[0].hash
95
+ * ```
96
+ */
97
+ export declare const buildChain: (entries: ReadonlyArray<{
98
+ kind: string;
99
+ subject: ReceiptSubject;
100
+ payload: TypedRef.Shape;
101
+ timestamp: HLC;
102
+ }>) => Effect.Effect<ReceiptEnvelope[]>;
103
+ /**
104
+ * Validate a receipt chain: genesis link, hash integrity, chain continuity, HLC ordering.
105
+ *
106
+ * Returns true on success or fails with an Error describing the violation.
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * const chain = yield* Receipt.buildChain(entries);
111
+ * const valid = yield* Receipt.validateChain(chain);
112
+ * // valid === true
113
+ * ```
114
+ */
115
+ export declare const validateChain: (chain: ReadonlyArray<ReceiptEnvelope>) => Effect.Effect<boolean, Error>;
116
+ /**
117
+ * Validate a receipt chain with detailed, structured error reporting.
118
+ *
119
+ * Returns `true` on success or fails with a typed `ChainValidationError`
120
+ * discriminated union (not_genesis | hash_mismatch | chain_break | hlc_not_increasing).
121
+ *
122
+ * @example
123
+ * ```ts
124
+ * import { Effect } from 'effect';
125
+ *
126
+ * const result = yield* Effect.either(Receipt.validateChainDetailed(chain));
127
+ * // result._tag === 'Right' on success
128
+ * // result._tag === 'Left' with .left.type on failure
129
+ * ```
130
+ */
131
+ export declare const validateChainDetailed: (chain: ReadonlyArray<ReceiptEnvelope>) => Effect.Effect<true, ChainValidationError>;
132
+ /**
133
+ * Check whether a receipt envelope is a genesis (root) envelope.
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * const chain = yield* Receipt.buildChain(entries);
138
+ * Receipt.isGenesis(chain[0]); // true
139
+ * Receipt.isGenesis(chain[1]); // false
140
+ * ```
141
+ */
142
+ export declare const isGenesis: (receipt: ReceiptEnvelope) => boolean;
143
+ /**
144
+ * Get the last (most recent) envelope in a chain.
145
+ *
146
+ * @example
147
+ * ```ts
148
+ * const latest = Receipt.head(chain);
149
+ * // latest === chain[chain.length - 1]
150
+ * ```
151
+ */
152
+ export declare const head: (chain: ReadonlyArray<ReceiptEnvelope>) => ReceiptEnvelope | undefined;
153
+ /**
154
+ * Get the first (genesis) envelope in a chain.
155
+ *
156
+ * @example
157
+ * ```ts
158
+ * const first = Receipt.tail(chain);
159
+ * // first === chain[0]
160
+ * ```
161
+ */
162
+ export declare const tail: (chain: ReadonlyArray<ReceiptEnvelope>) => ReceiptEnvelope | undefined;
163
+ /**
164
+ * Append a new entry to an existing chain, auto-linking to the previous hash.
165
+ *
166
+ * Optionally accepts explicit previous hashes for merge envelopes.
167
+ *
168
+ * @example
169
+ * ```ts
170
+ * const chain = yield* Receipt.buildChain([entry1]);
171
+ * const extended = yield* Receipt.append(chain, {
172
+ * kind: 'update', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts2,
173
+ * });
174
+ * // extended.length === 2
175
+ * ```
176
+ */
177
+ export declare const append: (chain: ReadonlyArray<ReceiptEnvelope>, entry: {
178
+ kind: string;
179
+ subject: ReceiptSubject;
180
+ payload: TypedRef.Shape;
181
+ timestamp: HLC;
182
+ }, previousHashes?: readonly string[]) => Effect.Effect<ReceiptEnvelope[]>;
183
+ /**
184
+ * Find an envelope in a chain by its content hash.
185
+ *
186
+ * @example
187
+ * ```ts
188
+ * const found = Receipt.findByHash(chain, targetHash);
189
+ * // found?.hash === targetHash
190
+ * ```
191
+ */
192
+ export declare const findByHash: (chain: ReadonlyArray<ReceiptEnvelope>, hash: string) => ReceiptEnvelope | undefined;
193
+ /**
194
+ * Find all envelopes in a chain matching a given kind.
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * const updates = Receipt.findByKind(chain, 'update');
199
+ * // updates contains all envelopes with kind === 'update'
200
+ * ```
201
+ */
202
+ export declare const findByKind: (chain: ReadonlyArray<ReceiptEnvelope>, kind: string) => ReceiptEnvelope[];
203
+ /**
204
+ * Generate an HMAC-SHA-256 key for signing receipt envelopes.
205
+ *
206
+ * @example
207
+ * ```ts
208
+ * const key = yield* Receipt.generateMACKey();
209
+ * const signed = yield* Receipt.macEnvelope(envelope, key);
210
+ * // signed.signature is a hex string
211
+ * ```
212
+ */
213
+ export declare const generateMACKey: () => Effect.Effect<CryptoKey, Error>;
214
+ /**
215
+ * Sign a receipt envelope with an HMAC key, adding a `signature` field.
216
+ *
217
+ * @example
218
+ * ```ts
219
+ * const key = yield* Receipt.generateMACKey();
220
+ * const signed = yield* Receipt.macEnvelope(envelope, key);
221
+ * // signed.signature !== undefined
222
+ * ```
223
+ */
224
+ export declare const macEnvelope: (envelope: ReceiptEnvelope, key: CryptoKey) => Effect.Effect<ReceiptEnvelope, Error>;
225
+ /**
226
+ * Verify an envelope's HMAC signature against a key.
227
+ *
228
+ * Returns false if the envelope has no signature.
229
+ *
230
+ * @example
231
+ * ```ts
232
+ * const valid = yield* Receipt.verifyMAC(signedEnvelope, key);
233
+ * // valid === true if signature matches
234
+ * ```
235
+ */
236
+ export declare const verifyMAC: (envelope: ReceiptEnvelope, key: CryptoKey) => Effect.Effect<boolean, Error>;
237
+ /**
238
+ * Receipt namespace -- chain validation and envelope construction.
239
+ *
240
+ * Build, validate, append, query, and sign linear receipt chains.
241
+ * Each envelope is content-addressed and linked to its predecessor.
242
+ * Supports HMAC signing/verification for tamper detection.
243
+ *
244
+ * @example
245
+ * ```ts
246
+ * import { Effect } from 'effect';
247
+ * import { Receipt, HLC } from '@czap/core';
248
+ *
249
+ * const program = Effect.gen(function* () {
250
+ * const ts = HLC.increment(HLC.create('node-1'), Date.now());
251
+ * const chain = yield* Receipt.buildChain([
252
+ * { kind: 'init', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts },
253
+ * ]);
254
+ * const valid = yield* Receipt.validateChain(chain);
255
+ * const latest = Receipt.head(chain);
256
+ * });
257
+ * ```
258
+ */
259
+ export declare const Receipt: {
260
+ GENESIS: string;
261
+ createEnvelope: (kind: string, subject: ReceiptSubject, payload: TypedRef.Shape, timestamp: HLC, previousHash: string | readonly string[]) => Effect.Effect<ReceiptEnvelope>;
262
+ buildChain: (entries: ReadonlyArray<{
263
+ kind: string;
264
+ subject: ReceiptSubject;
265
+ payload: TypedRef.Shape;
266
+ timestamp: HLC;
267
+ }>) => Effect.Effect<ReceiptEnvelope[]>;
268
+ validateChain: (chain: ReadonlyArray<ReceiptEnvelope>) => Effect.Effect<boolean, Error>;
269
+ validateChainDetailed: (chain: ReadonlyArray<ReceiptEnvelope>) => Effect.Effect<true, ChainValidationError>;
270
+ hashEnvelope: (envelope: ReceiptEnvelope) => Effect.Effect<string>;
271
+ isGenesis: (receipt: ReceiptEnvelope) => boolean;
272
+ head: (chain: ReadonlyArray<ReceiptEnvelope>) => ReceiptEnvelope | undefined;
273
+ tail: (chain: ReadonlyArray<ReceiptEnvelope>) => ReceiptEnvelope | undefined;
274
+ append: (chain: ReadonlyArray<ReceiptEnvelope>, entry: {
275
+ kind: string;
276
+ subject: ReceiptSubject;
277
+ payload: TypedRef.Shape;
278
+ timestamp: HLC;
279
+ }, previousHashes?: readonly string[]) => Effect.Effect<ReceiptEnvelope[]>;
280
+ findByHash: (chain: ReadonlyArray<ReceiptEnvelope>, hash: string) => ReceiptEnvelope | undefined;
281
+ findByKind: (chain: ReadonlyArray<ReceiptEnvelope>, kind: string) => ReceiptEnvelope[];
282
+ generateMACKey: () => Effect.Effect<CryptoKey, Error>;
283
+ macEnvelope: (envelope: ReceiptEnvelope, key: CryptoKey) => Effect.Effect<ReceiptEnvelope, Error>;
284
+ verifyMAC: (envelope: ReceiptEnvelope, key: CryptoKey) => Effect.Effect<boolean, Error>;
285
+ };
286
+ export declare namespace Receipt {
287
+ /** Alias for {@link ReceiptSubject}. */
288
+ type Subject = ReceiptSubject;
289
+ /** Alias for {@link ReceiptEnvelope}. */
290
+ type Envelope = ReceiptEnvelope;
291
+ /** Alias for {@link ChainValidationError}. */
292
+ type ChainError = ChainValidationError;
293
+ }
294
+ //# sourceMappingURL=receipt.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"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"}