@empressaio/atom-contract 1.7.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 (251) hide show
  1. package/CHANGELOG.md +360 -0
  2. package/README.md +379 -0
  3. package/dist/composition.d.ts +112 -0
  4. package/dist/composition.d.ts.map +1 -0
  5. package/dist/composition.js +80 -0
  6. package/dist/composition.js.map +1 -0
  7. package/dist/conformance/common.d.ts +21 -0
  8. package/dist/conformance/common.d.ts.map +1 -0
  9. package/dist/conformance/common.js +29 -0
  10. package/dist/conformance/common.js.map +1 -0
  11. package/dist/conformance/fixtures.d.ts +13 -0
  12. package/dist/conformance/fixtures.d.ts.map +1 -0
  13. package/dist/conformance/fixtures.js +63 -0
  14. package/dist/conformance/fixtures.js.map +1 -0
  15. package/dist/conformance/index.d.ts +11 -0
  16. package/dist/conformance/index.d.ts.map +1 -0
  17. package/dist/conformance/index.js +11 -0
  18. package/dist/conformance/index.js.map +1 -0
  19. package/dist/conformance/validate.d.ts +49 -0
  20. package/dist/conformance/validate.d.ts.map +1 -0
  21. package/dist/conformance/validate.js +138 -0
  22. package/dist/conformance/validate.js.map +1 -0
  23. package/dist/conformance/verify-chain.d.ts +25 -0
  24. package/dist/conformance/verify-chain.d.ts.map +1 -0
  25. package/dist/conformance/verify-chain.js +76 -0
  26. package/dist/conformance/verify-chain.js.map +1 -0
  27. package/dist/context.d.ts +134 -0
  28. package/dist/context.d.ts.map +1 -0
  29. package/dist/context.js +110 -0
  30. package/dist/context.js.map +1 -0
  31. package/dist/encumbrances/administrative-rule.d.ts +128 -0
  32. package/dist/encumbrances/administrative-rule.d.ts.map +1 -0
  33. package/dist/encumbrances/administrative-rule.js +18 -0
  34. package/dist/encumbrances/administrative-rule.js.map +1 -0
  35. package/dist/encumbrances/common.d.ts +153 -0
  36. package/dist/encumbrances/common.d.ts.map +1 -0
  37. package/dist/encumbrances/common.js +124 -0
  38. package/dist/encumbrances/common.js.map +1 -0
  39. package/dist/encumbrances/constraint-resolution.d.ts +169 -0
  40. package/dist/encumbrances/constraint-resolution.d.ts.map +1 -0
  41. package/dist/encumbrances/constraint-resolution.js +41 -0
  42. package/dist/encumbrances/constraint-resolution.js.map +1 -0
  43. package/dist/encumbrances/fixtures.d.ts +16 -0
  44. package/dist/encumbrances/fixtures.d.ts.map +1 -0
  45. package/dist/encumbrances/fixtures.js +107 -0
  46. package/dist/encumbrances/fixtures.js.map +1 -0
  47. package/dist/encumbrances/index.d.ts +15 -0
  48. package/dist/encumbrances/index.d.ts.map +1 -0
  49. package/dist/encumbrances/index.js +15 -0
  50. package/dist/encumbrances/index.js.map +1 -0
  51. package/dist/encumbrances/recorded-instrument.d.ts +131 -0
  52. package/dist/encumbrances/recorded-instrument.d.ts.map +1 -0
  53. package/dist/encumbrances/recorded-instrument.js +19 -0
  54. package/dist/encumbrances/recorded-instrument.js.map +1 -0
  55. package/dist/encumbrances/restriction-clause.d.ts +120 -0
  56. package/dist/encumbrances/restriction-clause.d.ts.map +1 -0
  57. package/dist/encumbrances/restriction-clause.js +17 -0
  58. package/dist/encumbrances/restriction-clause.js.map +1 -0
  59. package/dist/encumbrances/restriction-corpus.d.ts +44 -0
  60. package/dist/encumbrances/restriction-corpus.d.ts.map +1 -0
  61. package/dist/encumbrances/restriction-corpus.js +14 -0
  62. package/dist/encumbrances/restriction-corpus.js.map +1 -0
  63. package/dist/export/downloadable-atom.d.ts +133 -0
  64. package/dist/export/downloadable-atom.d.ts.map +1 -0
  65. package/dist/export/downloadable-atom.js +115 -0
  66. package/dist/export/downloadable-atom.js.map +1 -0
  67. package/dist/export/index.d.ts +6 -0
  68. package/dist/export/index.d.ts.map +1 -0
  69. package/dist/export/index.js +6 -0
  70. package/dist/export/index.js.map +1 -0
  71. package/dist/history.d.ts +124 -0
  72. package/dist/history.d.ts.map +1 -0
  73. package/dist/history.js +170 -0
  74. package/dist/history.js.map +1 -0
  75. package/dist/index.d.ts +29 -0
  76. package/dist/index.d.ts.map +1 -0
  77. package/dist/index.js +20 -0
  78. package/dist/index.js.map +1 -0
  79. package/dist/inline-reference.d.ts +60 -0
  80. package/dist/inline-reference.d.ts.map +1 -0
  81. package/dist/inline-reference.js +73 -0
  82. package/dist/inline-reference.js.map +1 -0
  83. package/dist/obligation.d.ts +131 -0
  84. package/dist/obligation.d.ts.map +1 -0
  85. package/dist/obligation.js +55 -0
  86. package/dist/obligation.js.map +1 -0
  87. package/dist/og/common.d.ts +253 -0
  88. package/dist/og/common.d.ts.map +1 -0
  89. package/dist/og/common.js +195 -0
  90. package/dist/og/common.js.map +1 -0
  91. package/dist/og/completion.d.ts +70 -0
  92. package/dist/og/completion.d.ts.map +1 -0
  93. package/dist/og/completion.js +22 -0
  94. package/dist/og/completion.js.map +1 -0
  95. package/dist/og/equipment-state.d.ts +55 -0
  96. package/dist/og/equipment-state.d.ts.map +1 -0
  97. package/dist/og/equipment-state.js +25 -0
  98. package/dist/og/equipment-state.js.map +1 -0
  99. package/dist/og/fixtures.d.ts +40 -0
  100. package/dist/og/fixtures.d.ts.map +1 -0
  101. package/dist/og/fixtures.js +255 -0
  102. package/dist/og/fixtures.js.map +1 -0
  103. package/dist/og/index.d.ts +23 -0
  104. package/dist/og/index.d.ts.map +1 -0
  105. package/dist/og/index.js +23 -0
  106. package/dist/og/index.js.map +1 -0
  107. package/dist/og/mineral-lease.d.ts +150 -0
  108. package/dist/og/mineral-lease.d.ts.map +1 -0
  109. package/dist/og/mineral-lease.js +24 -0
  110. package/dist/og/mineral-lease.js.map +1 -0
  111. package/dist/og/ownership-interest.d.ts +163 -0
  112. package/dist/og/ownership-interest.d.ts.map +1 -0
  113. package/dist/og/ownership-interest.js +36 -0
  114. package/dist/og/ownership-interest.js.map +1 -0
  115. package/dist/og/pad.d.ts +101 -0
  116. package/dist/og/pad.d.ts.map +1 -0
  117. package/dist/og/pad.js +19 -0
  118. package/dist/og/pad.js.map +1 -0
  119. package/dist/og/production-timeseries.d.ts +154 -0
  120. package/dist/og/production-timeseries.d.ts.map +1 -0
  121. package/dist/og/production-timeseries.js +37 -0
  122. package/dist/og/production-timeseries.js.map +1 -0
  123. package/dist/og/revenue-allocation-unit.d.ts +762 -0
  124. package/dist/og/revenue-allocation-unit.d.ts.map +1 -0
  125. package/dist/og/revenue-allocation-unit.js +105 -0
  126. package/dist/og/revenue-allocation-unit.js.map +1 -0
  127. package/dist/og/rrc-lease.d.ts +124 -0
  128. package/dist/og/rrc-lease.d.ts.map +1 -0
  129. package/dist/og/rrc-lease.js +29 -0
  130. package/dist/og/rrc-lease.js.map +1 -0
  131. package/dist/og/tract.d.ts +88 -0
  132. package/dist/og/tract.d.ts.map +1 -0
  133. package/dist/og/tract.js +30 -0
  134. package/dist/og/tract.js.map +1 -0
  135. package/dist/og/well.d.ts +201 -0
  136. package/dist/og/well.d.ts.map +1 -0
  137. package/dist/og/well.js +40 -0
  138. package/dist/og/well.js.map +1 -0
  139. package/dist/og/wellbore.d.ts +61 -0
  140. package/dist/og/wellbore.d.ts.map +1 -0
  141. package/dist/og/wellbore.js +25 -0
  142. package/dist/og/wellbore.js.map +1 -0
  143. package/dist/og/zone.d.ts +45 -0
  144. package/dist/og/zone.d.ts.map +1 -0
  145. package/dist/og/zone.js +16 -0
  146. package/dist/og/zone.js.map +1 -0
  147. package/dist/read-contract/common.d.ts +74 -0
  148. package/dist/read-contract/common.d.ts.map +1 -0
  149. package/dist/read-contract/common.js +54 -0
  150. package/dist/read-contract/common.js.map +1 -0
  151. package/dist/read-contract/consequence.d.ts +99 -0
  152. package/dist/read-contract/consequence.d.ts.map +1 -0
  153. package/dist/read-contract/consequence.js +46 -0
  154. package/dist/read-contract/consequence.js.map +1 -0
  155. package/dist/read-contract/fixtures.d.ts +8 -0
  156. package/dist/read-contract/fixtures.d.ts.map +1 -0
  157. package/dist/read-contract/fixtures.js +44 -0
  158. package/dist/read-contract/fixtures.js.map +1 -0
  159. package/dist/read-contract/index.d.ts +14 -0
  160. package/dist/read-contract/index.d.ts.map +1 -0
  161. package/dist/read-contract/index.js +14 -0
  162. package/dist/read-contract/index.js.map +1 -0
  163. package/dist/read-contract/model-attribution.d.ts +85 -0
  164. package/dist/read-contract/model-attribution.d.ts.map +1 -0
  165. package/dist/read-contract/model-attribution.js +30 -0
  166. package/dist/read-contract/model-attribution.js.map +1 -0
  167. package/dist/read-contract/read-contract.d.ts +455 -0
  168. package/dist/read-contract/read-contract.d.ts.map +1 -0
  169. package/dist/read-contract/read-contract.js +46 -0
  170. package/dist/read-contract/read-contract.js.map +1 -0
  171. package/dist/registration.d.ts +192 -0
  172. package/dist/registration.d.ts.map +1 -0
  173. package/dist/registration.js +15 -0
  174. package/dist/registration.js.map +1 -0
  175. package/dist/registry.d.ts +128 -0
  176. package/dist/registry.d.ts.map +1 -0
  177. package/dist/registry.js +122 -0
  178. package/dist/registry.js.map +1 -0
  179. package/dist/render.d.ts +30 -0
  180. package/dist/render.d.ts.map +1 -0
  181. package/dist/render.js +44 -0
  182. package/dist/render.js.map +1 -0
  183. package/dist/scope.d.ts +46 -0
  184. package/dist/scope.d.ts.map +1 -0
  185. package/dist/scope.js +17 -0
  186. package/dist/scope.js.map +1 -0
  187. package/dist/temporal/anticipatory-atom.d.ts +123 -0
  188. package/dist/temporal/anticipatory-atom.d.ts.map +1 -0
  189. package/dist/temporal/anticipatory-atom.js +124 -0
  190. package/dist/temporal/anticipatory-atom.js.map +1 -0
  191. package/dist/temporal/common.d.ts +47 -0
  192. package/dist/temporal/common.d.ts.map +1 -0
  193. package/dist/temporal/common.js +100 -0
  194. package/dist/temporal/common.js.map +1 -0
  195. package/dist/temporal/fixtures.d.ts +7 -0
  196. package/dist/temporal/fixtures.d.ts.map +1 -0
  197. package/dist/temporal/fixtures.js +21 -0
  198. package/dist/temporal/fixtures.js.map +1 -0
  199. package/dist/temporal/index.d.ts +13 -0
  200. package/dist/temporal/index.d.ts.map +1 -0
  201. package/dist/temporal/index.js +13 -0
  202. package/dist/temporal/index.js.map +1 -0
  203. package/dist/temporal/interval-query.d.ts +42 -0
  204. package/dist/temporal/interval-query.d.ts.map +1 -0
  205. package/dist/temporal/interval-query.js +49 -0
  206. package/dist/temporal/interval-query.js.map +1 -0
  207. package/dist/temporal/node-id.d.ts +112 -0
  208. package/dist/temporal/node-id.d.ts.map +1 -0
  209. package/dist/temporal/node-id.js +208 -0
  210. package/dist/temporal/node-id.js.map +1 -0
  211. package/dist/temporal/would-affect-edge.d.ts +66 -0
  212. package/dist/temporal/would-affect-edge.d.ts.map +1 -0
  213. package/dist/temporal/would-affect-edge.js +113 -0
  214. package/dist/temporal/would-affect-edge.js.map +1 -0
  215. package/dist/testing/index.d.ts +98 -0
  216. package/dist/testing/index.d.ts.map +1 -0
  217. package/dist/testing/index.js +225 -0
  218. package/dist/testing/index.js.map +1 -0
  219. package/dist/vda.d.ts +46 -0
  220. package/dist/vda.d.ts.map +1 -0
  221. package/dist/vda.js +42 -0
  222. package/dist/vda.js.map +1 -0
  223. package/dist/workspace/brief-run.d.ts +104 -0
  224. package/dist/workspace/brief-run.d.ts.map +1 -0
  225. package/dist/workspace/brief-run.js +32 -0
  226. package/dist/workspace/brief-run.js.map +1 -0
  227. package/dist/workspace/common.d.ts +42 -0
  228. package/dist/workspace/common.d.ts.map +1 -0
  229. package/dist/workspace/common.js +26 -0
  230. package/dist/workspace/common.js.map +1 -0
  231. package/dist/workspace/fixtures.d.ts +10 -0
  232. package/dist/workspace/fixtures.d.ts.map +1 -0
  233. package/dist/workspace/fixtures.js +93 -0
  234. package/dist/workspace/fixtures.js.map +1 -0
  235. package/dist/workspace/index.d.ts +13 -0
  236. package/dist/workspace/index.d.ts.map +1 -0
  237. package/dist/workspace/index.js +13 -0
  238. package/dist/workspace/index.js.map +1 -0
  239. package/dist/workspace/property-workspace.d.ts +148 -0
  240. package/dist/workspace/property-workspace.d.ts.map +1 -0
  241. package/dist/workspace/property-workspace.js +21 -0
  242. package/dist/workspace/property-workspace.js.map +1 -0
  243. package/dist/workspace/workspace-attachment.d.ts +99 -0
  244. package/dist/workspace/workspace-attachment.d.ts.map +1 -0
  245. package/dist/workspace/workspace-attachment.js +35 -0
  246. package/dist/workspace/workspace-attachment.js.map +1 -0
  247. package/dist/workspace/workspace-share-edge.d.ts +115 -0
  248. package/dist/workspace/workspace-share-edge.d.ts.map +1 -0
  249. package/dist/workspace/workspace-share-edge.js +22 -0
  250. package/dist/workspace/workspace-share-edge.js.map +1 -0
  251. package/package.json +107 -0
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Stable node ID derivation and anchor validation (ADR-011 discipline).
3
+ *
4
+ * Resolver contract: DID derivation follows two patterns per ADR-025:
5
+ * 1. Public identifier embedding: well_<api14>, rrclease_<district>-<leaseNo>,
6
+ * tract_<county>-<abstract> where the public identifier IS the stable key.
7
+ * 2. Hashed derivation: evt_, intr_, oblg_, prodts_, unit_, equip_ use
8
+ * SHA-256(source\0externalId) for entities without global public keys.
9
+ *
10
+ * A manually constructed ID that is not anchored to its real derivation
11
+ * inputs is rejected by the corresponding validation function.
12
+ */
13
+ export interface EvtNodeAnchor {
14
+ readonly source: string;
15
+ readonly externalId: string;
16
+ }
17
+ /**
18
+ * Derive the canonical evt_ node ID for a source/external_id pair.
19
+ * Deterministic across runtimes — SHA-256 digest truncated to 16 hex chars.
20
+ */
21
+ export declare function deriveEvtNodeId(source: string, externalId: string): string;
22
+ /** True when `nodeId` carries the evt_ prefix. */
23
+ export declare function isEvtNodeId(nodeId: string): boolean;
24
+ /**
25
+ * Verify that `nodeId` matches the canonical derivation for the anchor.
26
+ * Rejects manually constructed IDs not anchored to the pair.
27
+ */
28
+ export declare function validateEvtNodeAnchor(nodeId: string, anchor: EvtNodeAnchor): boolean;
29
+ /**
30
+ * API-14 format: exactly 14 digits, optionally with hyphens at positions
31
+ * 2 and 7 (state code, county code). Examples: 42-123-12345-00-00 or
32
+ * 42123123450000 (both valid).
33
+ */
34
+ export declare const API_14_PATTERN: RegExp;
35
+ /**
36
+ * Normalize API-14 to canonical 14-digit format (strip hyphens).
37
+ */
38
+ export declare function normalizeApi14(api14: string): string;
39
+ /**
40
+ * Derive the canonical well_ node ID from an API-14 identifier.
41
+ * API-14 is the stable global key; the DID embeds it legibly.
42
+ * Format: well_<api14> where api14 is the 14-digit normalized form.
43
+ */
44
+ export declare function deriveWellNodeId(api14: string): string;
45
+ /**
46
+ * Derive the canonical rrc-lease node ID from district and lease number.
47
+ * Format: rrclease_<district>-<leaseNo> (public identifiers legibly embedded).
48
+ */
49
+ export declare function deriveRrcLeaseNodeId(district: string, leaseNo: string): string;
50
+ /**
51
+ * Derive the canonical tract node ID from county and abstract number.
52
+ * Format: tract_<county>-<abstract> where abstract-keyed; for non-abstract
53
+ * tracts, use the hashed derivation (deriveTractNodeIdHashed).
54
+ */
55
+ export declare function deriveTractNodeId(county: string, abstract: string): string;
56
+ /**
57
+ * Derive a hashed tract node ID for tracts without abstract numbers
58
+ * (metes and bounds, etc.). Uses the same hashing pattern as evt_.
59
+ */
60
+ export declare function deriveTractNodeIdHashed(source: string, externalId: string): string;
61
+ /**
62
+ * Derive an ownership-interest node ID (hashed derivation).
63
+ * Format: intr_<hash> from (source, externalId).
64
+ */
65
+ export declare function deriveInterestNodeId(source: string, externalId: string): string;
66
+ /**
67
+ * Derive an obligation node ID (hashed derivation, core type).
68
+ * Format: oblg_<hash> from (source, externalId).
69
+ */
70
+ export declare function deriveObligationNodeId(source: string, externalId: string): string;
71
+ /**
72
+ * Derive a production-timeseries node ID (hashed derivation).
73
+ * Format: prodts_<hash> from (source, externalId).
74
+ */
75
+ export declare function deriveProductionTimeseriesNodeId(source: string, externalId: string): string;
76
+ /**
77
+ * Derive a revenue-allocation-unit node ID (hashed derivation).
78
+ * Format: unit_<hash> from (source, externalId).
79
+ */
80
+ export declare function deriveUnitNodeId(source: string, externalId: string): string;
81
+ /**
82
+ * Derive an equipment-state node ID (hashed derivation).
83
+ * Format: equip_<hash> from (source, externalId).
84
+ */
85
+ export declare function deriveEquipmentNodeId(source: string, externalId: string): string;
86
+ /**
87
+ * Derive a wellbore node ID (hashed derivation, keyed to parent well + sidetrack).
88
+ * Format: wbore_<hash> from (source, externalId).
89
+ */
90
+ export declare function deriveWellboreNodeId(source: string, externalId: string): string;
91
+ /**
92
+ * Derive a completion node ID (hashed derivation).
93
+ * Format: cmpl_<hash> from (source, externalId).
94
+ */
95
+ export declare function deriveCompletionNodeId(source: string, externalId: string): string;
96
+ /**
97
+ * Derive a zone node ID (hashed derivation for custom zones; public zones
98
+ * may use formation name directly if that's the stable identifier).
99
+ * Format: zone_<hash> from (source, externalId).
100
+ */
101
+ export declare function deriveZoneNodeId(source: string, externalId: string): string;
102
+ /**
103
+ * Derive a pad node ID (hashed derivation, derived entity).
104
+ * Format: pad_<hash> from (source, externalId).
105
+ */
106
+ export declare function derivePadNodeId(source: string, externalId: string): string;
107
+ /**
108
+ * Derive a mineral-lease node ID (hashed derivation).
109
+ * Format: mlease_<hash> from (source, externalId).
110
+ */
111
+ export declare function deriveLeaseNodeId(source: string, externalId: string): string;
112
+ //# sourceMappingURL=node-id.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node-id.d.ts","sourceRoot":"","sources":["../../src/temporal/node-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED,kDAAkD;AAClD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,GACpB,OAAO,CAGT;AAMD;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAwC,CAAC;AAEpE;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK9E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMlF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMjF;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM3F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMhF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAM5E"}
@@ -0,0 +1,208 @@
1
+ /**
2
+ * Stable node ID derivation and anchor validation (ADR-011 discipline).
3
+ *
4
+ * Resolver contract: DID derivation follows two patterns per ADR-025:
5
+ * 1. Public identifier embedding: well_<api14>, rrclease_<district>-<leaseNo>,
6
+ * tract_<county>-<abstract> where the public identifier IS the stable key.
7
+ * 2. Hashed derivation: evt_, intr_, oblg_, prodts_, unit_, equip_ use
8
+ * SHA-256(source\0externalId) for entities without global public keys.
9
+ *
10
+ * A manually constructed ID that is not anchored to its real derivation
11
+ * inputs is rejected by the corresponding validation function.
12
+ */
13
+ import { createHash } from "node:crypto";
14
+ import { hasNodeTypePrefix } from "./common.js";
15
+ /**
16
+ * Derive the canonical evt_ node ID for a source/external_id pair.
17
+ * Deterministic across runtimes — SHA-256 digest truncated to 16 hex chars.
18
+ */
19
+ export function deriveEvtNodeId(source, externalId) {
20
+ const digest = createHash("sha256")
21
+ .update(`${source}\0${externalId}`, "utf8")
22
+ .digest("hex")
23
+ .slice(0, 16);
24
+ return `evt_${digest}`;
25
+ }
26
+ /** True when `nodeId` carries the evt_ prefix. */
27
+ export function isEvtNodeId(nodeId) {
28
+ return hasNodeTypePrefix(nodeId, "evt_");
29
+ }
30
+ /**
31
+ * Verify that `nodeId` matches the canonical derivation for the anchor.
32
+ * Rejects manually constructed IDs not anchored to the pair.
33
+ */
34
+ export function validateEvtNodeAnchor(nodeId, anchor) {
35
+ if (!isEvtNodeId(nodeId))
36
+ return false;
37
+ return nodeId === deriveEvtNodeId(anchor.source, anchor.externalId);
38
+ }
39
+ // ============================================================================
40
+ // O&G DID derivation functions (ADR-025)
41
+ // ============================================================================
42
+ /**
43
+ * API-14 format: exactly 14 digits, optionally with hyphens at positions
44
+ * 2 and 7 (state code, county code). Examples: 42-123-12345-00-00 or
45
+ * 42123123450000 (both valid).
46
+ */
47
+ export const API_14_PATTERN = /^\d{2}-?\d{3}-?\d{5}-?\d{2}-?\d{2}$/;
48
+ /**
49
+ * Normalize API-14 to canonical 14-digit format (strip hyphens).
50
+ */
51
+ export function normalizeApi14(api14) {
52
+ return api14.replace(/-/g, "");
53
+ }
54
+ /**
55
+ * Derive the canonical well_ node ID from an API-14 identifier.
56
+ * API-14 is the stable global key; the DID embeds it legibly.
57
+ * Format: well_<api14> where api14 is the 14-digit normalized form.
58
+ */
59
+ export function deriveWellNodeId(api14) {
60
+ if (!API_14_PATTERN.test(api14)) {
61
+ throw new Error(`Invalid API-14 format: ${api14}`);
62
+ }
63
+ return `well_${normalizeApi14(api14)}`;
64
+ }
65
+ /**
66
+ * Derive the canonical rrc-lease node ID from district and lease number.
67
+ * Format: rrclease_<district>-<leaseNo> (public identifiers legibly embedded).
68
+ */
69
+ export function deriveRrcLeaseNodeId(district, leaseNo) {
70
+ if (!district || !leaseNo) {
71
+ throw new Error("District and leaseNo are required");
72
+ }
73
+ return `rrclease_${district}-${leaseNo}`;
74
+ }
75
+ /**
76
+ * Derive the canonical tract node ID from county and abstract number.
77
+ * Format: tract_<county>-<abstract> where abstract-keyed; for non-abstract
78
+ * tracts, use the hashed derivation (deriveTractNodeIdHashed).
79
+ */
80
+ export function deriveTractNodeId(county, abstract) {
81
+ if (!county || !abstract) {
82
+ throw new Error("County and abstract are required");
83
+ }
84
+ return `tract_${county}-${abstract}`;
85
+ }
86
+ /**
87
+ * Derive a hashed tract node ID for tracts without abstract numbers
88
+ * (metes and bounds, etc.). Uses the same hashing pattern as evt_.
89
+ */
90
+ export function deriveTractNodeIdHashed(source, externalId) {
91
+ const digest = createHash("sha256")
92
+ .update(`${source}\0${externalId}`, "utf8")
93
+ .digest("hex")
94
+ .slice(0, 16);
95
+ return `tract_${digest}`;
96
+ }
97
+ /**
98
+ * Derive an ownership-interest node ID (hashed derivation).
99
+ * Format: intr_<hash> from (source, externalId).
100
+ */
101
+ export function deriveInterestNodeId(source, externalId) {
102
+ const digest = createHash("sha256")
103
+ .update(`${source}\0${externalId}`, "utf8")
104
+ .digest("hex")
105
+ .slice(0, 16);
106
+ return `intr_${digest}`;
107
+ }
108
+ /**
109
+ * Derive an obligation node ID (hashed derivation, core type).
110
+ * Format: oblg_<hash> from (source, externalId).
111
+ */
112
+ export function deriveObligationNodeId(source, externalId) {
113
+ const digest = createHash("sha256")
114
+ .update(`${source}\0${externalId}`, "utf8")
115
+ .digest("hex")
116
+ .slice(0, 16);
117
+ return `oblg_${digest}`;
118
+ }
119
+ /**
120
+ * Derive a production-timeseries node ID (hashed derivation).
121
+ * Format: prodts_<hash> from (source, externalId).
122
+ */
123
+ export function deriveProductionTimeseriesNodeId(source, externalId) {
124
+ const digest = createHash("sha256")
125
+ .update(`${source}\0${externalId}`, "utf8")
126
+ .digest("hex")
127
+ .slice(0, 16);
128
+ return `prodts_${digest}`;
129
+ }
130
+ /**
131
+ * Derive a revenue-allocation-unit node ID (hashed derivation).
132
+ * Format: unit_<hash> from (source, externalId).
133
+ */
134
+ export function deriveUnitNodeId(source, externalId) {
135
+ const digest = createHash("sha256")
136
+ .update(`${source}\0${externalId}`, "utf8")
137
+ .digest("hex")
138
+ .slice(0, 16);
139
+ return `unit_${digest}`;
140
+ }
141
+ /**
142
+ * Derive an equipment-state node ID (hashed derivation).
143
+ * Format: equip_<hash> from (source, externalId).
144
+ */
145
+ export function deriveEquipmentNodeId(source, externalId) {
146
+ const digest = createHash("sha256")
147
+ .update(`${source}\0${externalId}`, "utf8")
148
+ .digest("hex")
149
+ .slice(0, 16);
150
+ return `equip_${digest}`;
151
+ }
152
+ /**
153
+ * Derive a wellbore node ID (hashed derivation, keyed to parent well + sidetrack).
154
+ * Format: wbore_<hash> from (source, externalId).
155
+ */
156
+ export function deriveWellboreNodeId(source, externalId) {
157
+ const digest = createHash("sha256")
158
+ .update(`${source}\0${externalId}`, "utf8")
159
+ .digest("hex")
160
+ .slice(0, 16);
161
+ return `wbore_${digest}`;
162
+ }
163
+ /**
164
+ * Derive a completion node ID (hashed derivation).
165
+ * Format: cmpl_<hash> from (source, externalId).
166
+ */
167
+ export function deriveCompletionNodeId(source, externalId) {
168
+ const digest = createHash("sha256")
169
+ .update(`${source}\0${externalId}`, "utf8")
170
+ .digest("hex")
171
+ .slice(0, 16);
172
+ return `cmpl_${digest}`;
173
+ }
174
+ /**
175
+ * Derive a zone node ID (hashed derivation for custom zones; public zones
176
+ * may use formation name directly if that's the stable identifier).
177
+ * Format: zone_<hash> from (source, externalId).
178
+ */
179
+ export function deriveZoneNodeId(source, externalId) {
180
+ const digest = createHash("sha256")
181
+ .update(`${source}\0${externalId}`, "utf8")
182
+ .digest("hex")
183
+ .slice(0, 16);
184
+ return `zone_${digest}`;
185
+ }
186
+ /**
187
+ * Derive a pad node ID (hashed derivation, derived entity).
188
+ * Format: pad_<hash> from (source, externalId).
189
+ */
190
+ export function derivePadNodeId(source, externalId) {
191
+ const digest = createHash("sha256")
192
+ .update(`${source}\0${externalId}`, "utf8")
193
+ .digest("hex")
194
+ .slice(0, 16);
195
+ return `pad_${digest}`;
196
+ }
197
+ /**
198
+ * Derive a mineral-lease node ID (hashed derivation).
199
+ * Format: mlease_<hash> from (source, externalId).
200
+ */
201
+ export function deriveLeaseNodeId(source, externalId) {
202
+ const digest = createHash("sha256")
203
+ .update(`${source}\0${externalId}`, "utf8")
204
+ .digest("hex")
205
+ .slice(0, 16);
206
+ return `mlease_${digest}`;
207
+ }
208
+ //# sourceMappingURL=node-id.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node-id.js","sourceRoot":"","sources":["../../src/temporal/node-id.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Structural would_affect edges — event node to subject node.
3
+ *
4
+ * Carries existence only (effective date + anchor). Effect-probability
5
+ * is a derived atom re-estimated over time and is NOT stored on this edge.
6
+ *
7
+ * `immutable: true` is a TypeScript discriminated-union tag communicating
8
+ * the contract. Backend write paths MUST reject updates to deposited
9
+ * would_affect edges; supersession is via a new edge deposit.
10
+ */
11
+ import { z } from "zod";
12
+ /** Literal true tag — structural, never updated after deposit. */
13
+ export type WouldAffectImmutableTag = true;
14
+ /**
15
+ * Structural edge from an event node to a subject node.
16
+ *
17
+ * - `sourceNodeId` MUST carry the `evt_` prefix.
18
+ * - `targetSubjectId` carries a subject prefix (`parcel_`, `jurisdiction_`, etc.).
19
+ * - `effectiveDate` is the ISO 8601 calendar date the event takes effect.
20
+ */
21
+ export interface WouldAffectEdge {
22
+ readonly type: "would_affect";
23
+ readonly sourceNodeId: string;
24
+ readonly targetSubjectId: string;
25
+ readonly effectiveDate: string;
26
+ readonly immutable: WouldAffectImmutableTag;
27
+ }
28
+ export declare const WOULD_AFFECT_EDGE_SCHEMA: z.ZodReadonly<z.ZodObject<{
29
+ type: z.ZodLiteral<"would_affect">;
30
+ sourceNodeId: z.ZodString;
31
+ targetSubjectId: z.ZodString;
32
+ effectiveDate: z.ZodString;
33
+ immutable: z.ZodLiteral<true>;
34
+ }, "strip", z.ZodTypeAny, {
35
+ type: "would_affect";
36
+ effectiveDate: string;
37
+ sourceNodeId: string;
38
+ targetSubjectId: string;
39
+ immutable: true;
40
+ }, {
41
+ type: "would_affect";
42
+ effectiveDate: string;
43
+ sourceNodeId: string;
44
+ targetSubjectId: string;
45
+ immutable: true;
46
+ }>>;
47
+ export type WouldAffectEdgeValidationCode = "invalid-source-prefix" | "invalid-target-prefix" | "missing-effective-date" | "invalid-effective-date" | "invalid-immutable-tag";
48
+ export interface WouldAffectEdgeValidationIssue {
49
+ readonly code: WouldAffectEdgeValidationCode;
50
+ readonly path: string;
51
+ readonly message: string;
52
+ }
53
+ export interface WouldAffectEdgeValidationResult {
54
+ readonly ok: boolean;
55
+ readonly edge?: WouldAffectEdge;
56
+ readonly issues: ReadonlyArray<WouldAffectEdgeValidationIssue>;
57
+ }
58
+ /**
59
+ * Validate a would_affect edge. Rejects missing/non-ISO effectiveDate and
60
+ * sourceNodeId values that do not carry the evt_ prefix.
61
+ */
62
+ export declare function validateWouldAffectEdge(input: unknown): WouldAffectEdgeValidationResult;
63
+ /** Edge union for the TCE graph write surface (v1.6.0). */
64
+ export type EdgeType = WouldAffectEdge;
65
+ export declare function createWouldAffectEdge(input: Omit<WouldAffectEdge, "type" | "immutable">): WouldAffectEdge;
66
+ //# sourceMappingURL=would-affect-edge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"would-affect-edge.d.ts","sourceRoot":"","sources":["../../src/temporal/would-affect-edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,kEAAkE;AAClE,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;CAC7C;AAED,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;GAQxB,CAAC;AAEd,MAAM,MAAM,6BAA6B,GACrC,uBAAuB,GACvB,uBAAuB,GACvB,wBAAwB,GACxB,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,8BAA8B,CAAC,CAAC;CAChE;AAQD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,+BAA+B,CAmFvF;AAED,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC;AAEvC,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,WAAW,CAAC,GACjD,eAAe,CASjB"}
@@ -0,0 +1,113 @@
1
+ /**
2
+ * Structural would_affect edges — event node to subject node.
3
+ *
4
+ * Carries existence only (effective date + anchor). Effect-probability
5
+ * is a derived atom re-estimated over time and is NOT stored on this edge.
6
+ *
7
+ * `immutable: true` is a TypeScript discriminated-union tag communicating
8
+ * the contract. Backend write paths MUST reject updates to deposited
9
+ * would_affect edges; supersession is via a new edge deposit.
10
+ */
11
+ import { z } from "zod";
12
+ import { detectNodeTypePrefix, isIsoDate } from "./common.js";
13
+ import { isEvtNodeId } from "./node-id.js";
14
+ export const WOULD_AFFECT_EDGE_SCHEMA = z
15
+ .object({
16
+ type: z.literal("would_affect"),
17
+ sourceNodeId: z.string().min(1),
18
+ targetSubjectId: z.string().min(1),
19
+ effectiveDate: z.string().min(1),
20
+ immutable: z.literal(true),
21
+ })
22
+ .readonly();
23
+ const SUBJECT_PREFIXES = ["parcel_", "jurisdiction_", "code-section_", "security_"];
24
+ function hasSubjectPrefix(nodeId) {
25
+ return SUBJECT_PREFIXES.some((p) => nodeId.startsWith(p));
26
+ }
27
+ /**
28
+ * Validate a would_affect edge. Rejects missing/non-ISO effectiveDate and
29
+ * sourceNodeId values that do not carry the evt_ prefix.
30
+ */
31
+ export function validateWouldAffectEdge(input) {
32
+ const issues = [];
33
+ const parsed = WOULD_AFFECT_EDGE_SCHEMA.safeParse(input);
34
+ if (!parsed.success) {
35
+ const missingDate = typeof input === "object" &&
36
+ input !== null &&
37
+ !("effectiveDate" in input);
38
+ if (missingDate) {
39
+ return {
40
+ ok: false,
41
+ issues: [
42
+ {
43
+ code: "missing-effective-date",
44
+ path: "effectiveDate",
45
+ message: "effectiveDate is required on would_affect edges",
46
+ },
47
+ ],
48
+ };
49
+ }
50
+ return {
51
+ ok: false,
52
+ issues: [
53
+ {
54
+ code: "invalid-effective-date",
55
+ path: "",
56
+ message: parsed.error.message,
57
+ },
58
+ ],
59
+ };
60
+ }
61
+ const data = parsed.data;
62
+ if (!isEvtNodeId(data.sourceNodeId)) {
63
+ issues.push({
64
+ code: "invalid-source-prefix",
65
+ path: "sourceNodeId",
66
+ message: `sourceNodeId must carry evt_ prefix; got "${data.sourceNodeId}"`,
67
+ });
68
+ }
69
+ if (!hasSubjectPrefix(data.targetSubjectId)) {
70
+ const detected = detectNodeTypePrefix(data.targetSubjectId);
71
+ issues.push({
72
+ code: "invalid-target-prefix",
73
+ path: "targetSubjectId",
74
+ message: detected
75
+ ? `targetSubjectId must be a subject node (parcel_, jurisdiction_, etc.); got prefix "${detected}"`
76
+ : `targetSubjectId must carry a known subject prefix; got "${data.targetSubjectId}"`,
77
+ });
78
+ }
79
+ if (!data.effectiveDate || data.effectiveDate.trim() === "") {
80
+ issues.push({
81
+ code: "missing-effective-date",
82
+ path: "effectiveDate",
83
+ message: "effectiveDate is required on would_affect edges",
84
+ });
85
+ }
86
+ else if (!isIsoDate(data.effectiveDate)) {
87
+ issues.push({
88
+ code: "invalid-effective-date",
89
+ path: "effectiveDate",
90
+ message: `effectiveDate must be a valid ISO 8601 date (YYYY-MM-DD); got "${data.effectiveDate}"`,
91
+ });
92
+ }
93
+ if (data.immutable !== true) {
94
+ issues.push({
95
+ code: "invalid-immutable-tag",
96
+ path: "immutable",
97
+ message: 'would_affect edges require immutable: true',
98
+ });
99
+ }
100
+ if (issues.length > 0) {
101
+ return { ok: false, issues };
102
+ }
103
+ return { ok: true, edge: data, issues: [] };
104
+ }
105
+ export function createWouldAffectEdge(input) {
106
+ const candidate = { ...input, type: "would_affect", immutable: true };
107
+ const result = validateWouldAffectEdge(candidate);
108
+ if (!result.ok || !result.edge) {
109
+ throw new Error(result.issues.map((i) => i.message).join("; ") || "invalid would_affect edge");
110
+ }
111
+ return result.edge;
112
+ }
113
+ //# sourceMappingURL=would-affect-edge.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"would-affect-edge.js","sourceRoot":"","sources":["../../src/temporal/would-affect-edge.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Testing utilities for `@empressaio/atom-contract`.
3
+ *
4
+ * Consumer atom registrations import {@link runAtomContractTests} to
5
+ * prove their registration is well-formed in one function call. The
6
+ * in-memory event service lets unit tests exercise the
7
+ * `EventAnchoringService` interface without spinning up Postgres.
8
+ *
9
+ * This module is intentionally **not** re-exported from the main barrel
10
+ * (`src/index.ts`) — it lives behind the `./testing` subpath so production
11
+ * bundles never pull it in.
12
+ */
13
+ import { type AtomRegistry } from "../registry.js";
14
+ import type { AtomRegistration, AtomMode, AnyAtomRegistration } from "../registration.js";
15
+ import type { EventAnchoringService } from "../history.js";
16
+ import { type ValidateAtomConformanceInput } from "../conformance/validate.js";
17
+ /**
18
+ * Convenience wrapper around {@link createAtomRegistry} for tests. Accepts
19
+ * an initial set of registrations so a single call can register and
20
+ * return the registry.
21
+ */
22
+ export declare function createTestRegistry(initial?: ReadonlyArray<AnyAtomRegistration>): AtomRegistry;
23
+ /**
24
+ * In-memory {@link EventAnchoringService} implementation. Mirrors
25
+ * {@link PostgresEventAnchoringService}'s chain-hash semantics so unit
26
+ * tests can assert against the same invariants without touching Postgres.
27
+ */
28
+ export declare function createInMemoryEventService(): EventAnchoringService;
29
+ /**
30
+ * Optional fixture callback an atom may pass to seed the contract suite
31
+ * with whatever shape its `contextSummary` expects.
32
+ */
33
+ export interface AtomContractFixture {
34
+ /** Entity id the contract suite will pass to `contextSummary`. */
35
+ entityId: string;
36
+ /** Optional pre-registration setup (DB seed, fetch mocking, etc.). */
37
+ setUp?: () => Promise<void> | void;
38
+ /** Cleanup hook invoked after the suite. */
39
+ tearDown?: () => Promise<void> | void;
40
+ }
41
+ export interface AtomContractOptions {
42
+ /** Per-atom fixture. Defaults to `{ entityId: "contract-test-id" }`. */
43
+ withFixture?: AtomContractFixture;
44
+ /**
45
+ * Other atoms that must be in the registry for composition validation
46
+ * to pass. Defaults to `[]`.
47
+ */
48
+ alsoRegister?: ReadonlyArray<AnyAtomRegistration>;
49
+ }
50
+ /**
51
+ * Contract test suite consumer atom registrations import to prove
52
+ * compliance with one function call.
53
+ *
54
+ * Asserts:
55
+ * 1. identity is present and `entityType` is non-empty,
56
+ * 2. `defaultMode` is in `supportedModes`,
57
+ * 3. `contextSummary` returns a valid four-layer shape with
58
+ * `historyProvenance` and `scopeFiltered`,
59
+ * 4. every composition edge resolves against `alsoRegister + this`,
60
+ * 5. inline-reference round-trips: `parse(serialize(ref))[0].reference`
61
+ * equals `ref` modulo `mode`.
62
+ *
63
+ * @example
64
+ * import { describe } from "vitest";
65
+ * import { runAtomContractTests } from "@empressaio/atom-contract/testing";
66
+ * import { taskAtom } from "./task.reg.js";
67
+ * describe("task atom contract", () => {
68
+ * runAtomContractTests(taskAtom, { withFixture: { entityId: "t1" } });
69
+ * });
70
+ */
71
+ export declare function runAtomContractTests<TType extends string, TSupported extends ReadonlyArray<AtomMode>>(registration: AtomRegistration<TType, TSupported>, opts?: AtomContractOptions): void;
72
+ /** Default fixture used when an atom passes none. Exported for tests. */
73
+ export declare const DEFAULT_CONTRACT_FIXTURE: AtomContractFixture;
74
+ export interface AtomConformanceTestOptions {
75
+ /** Data-level atoms require signed history; app-level skip it. */
76
+ tier?: "data" | "app";
77
+ signedHistory?: {
78
+ events: unknown[];
79
+ };
80
+ }
81
+ /**
82
+ * Conformance test suite for the architecture-homes target shape (doc 02).
83
+ * Validates read-contract, accessPolicy, and signed-history at runtime.
84
+ *
85
+ * @example
86
+ * import { describe } from "vitest";
87
+ * import { runAtomConformanceTests } from "@empressaio/atom-contract/testing";
88
+ * describe("code-section conformance", () => {
89
+ * runAtomConformanceTests("code-section", {
90
+ * tier: "data",
91
+ * readContract: emission.readContract,
92
+ * accessPolicy: "public-free",
93
+ * signedHistory: { events: emission.events },
94
+ * });
95
+ * });
96
+ */
97
+ export declare function runAtomConformanceTests(label: string, input: ValidateAtomConformanceInput, _opts?: AtomConformanceTestOptions): void;
98
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAMvE,OAAO,KAAK,EACV,gBAAgB,EAEhB,QAAQ,EACR,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAGV,qBAAqB,EAEtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,4BAA4B,CAAC;AAGpC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,aAAa,CAAC,mBAAmB,CAAM,GAC/C,YAAY,CASd;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,qBAAqB,CAsElE;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,SAAS,MAAM,EACpB,UAAU,SAAS,aAAa,CAAC,QAAQ,CAAC,EAE1C,YAAY,EAAE,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,EACjD,IAAI,GAAE,mBAAwB,GAC7B,IAAI,CAmEN;AAED,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,EAAE,mBAEtC,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,aAAa,CAAC,EAAE;QAAE,MAAM,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;CACvC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,4BAA4B,EACnC,KAAK,GAAE,0BAA+B,GACrC,IAAI,CAiBN"}