@coasys/ad4m 0.13.0-test-interpretation-2 → 0.13.0-test-model-layer

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 (254) hide show
  1. package/lib/index.cjs +1982 -498
  2. package/lib/index.js +1982 -499
  3. package/lib/src/ai/AIClient.js +6 -3
  4. package/lib/src/apiClient.d.ts +40 -4
  5. package/lib/src/apiClient.js +149 -9
  6. package/lib/src/index.d.ts +3 -1
  7. package/lib/src/index.js +2 -0
  8. package/lib/src/model/Ad4mModel.d.ts +6 -5
  9. package/lib/src/model/Ad4mModel.js +246 -29
  10. package/lib/src/model/Ad4mModel.test.js +480 -735
  11. package/lib/src/model/decorators.d.ts +147 -4
  12. package/lib/src/model/decorators.js +70 -24
  13. package/lib/src/model/model-manifest.d.ts +41 -0
  14. package/lib/src/model/model-manifest.js +11 -0
  15. package/lib/src/model/query-sparql.test.js +92 -10
  16. package/lib/src/model/shacl-gen.js +33 -0
  17. package/lib/src/model/types.d.ts +9 -0
  18. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +33 -33
  19. package/lib/src/perspectives/AutoProcessor.d.ts +90 -24
  20. package/lib/src/perspectives/FlowInstance.d.ts +187 -0
  21. package/lib/src/perspectives/FlowInstance.js +336 -0
  22. package/lib/src/perspectives/FlowModels.d.ts +94 -0
  23. package/lib/src/perspectives/FlowModels.js +182 -0
  24. package/lib/src/perspectives/InterpretationModels.d.ts +12 -22
  25. package/lib/src/perspectives/InterpretationModels.js +2 -6
  26. package/lib/src/perspectives/PerspectiveClient.d.ts +68 -7
  27. package/lib/src/perspectives/PerspectiveClient.js +105 -10
  28. package/lib/src/perspectives/PerspectiveProxy.d.ts +142 -57
  29. package/lib/src/perspectives/PerspectiveProxy.js +388 -274
  30. package/lib/src/shacl/SHACLFlow.d.ts +273 -47
  31. package/lib/src/shacl/SHACLFlow.js +397 -88
  32. package/lib/src/shacl/SHACLShape.d.ts +8 -0
  33. package/lib/src/shacl/SHACLShape.js +17 -0
  34. package/lib/src/shacl/SHACLShape.test.js +82 -0
  35. package/package.json +2 -2
  36. package/src/ai/AIClient.ts +6 -3
  37. package/src/apiClient.test.ts +227 -0
  38. package/src/apiClient.ts +185 -9
  39. package/src/index.ts +3 -1
  40. package/src/model/Ad4mModel.test.ts +645 -0
  41. package/src/model/Ad4mModel.ts +245 -26
  42. package/src/model/decorators.ts +216 -35
  43. package/src/model/relation-filtering.test.ts +70 -20
  44. package/src/model/shacl-gen.ts +36 -0
  45. package/src/model/shacl-roundtrip.test.ts +130 -0
  46. package/src/model/types.ts +7 -0
  47. package/src/perspectives/AutoProcessor.ts +94 -24
  48. package/src/perspectives/FlowInstance.ts +369 -0
  49. package/src/perspectives/FlowModels.ts +157 -0
  50. package/src/perspectives/InterpretationModels.ts +13 -25
  51. package/src/perspectives/PerspectiveClient.test.ts +67 -6
  52. package/src/perspectives/PerspectiveClient.ts +142 -12
  53. package/src/perspectives/PerspectiveProxy.test.ts +406 -0
  54. package/src/perspectives/PerspectiveProxy.ts +459 -289
  55. package/src/perspectives/shacl-rpc.test.ts +258 -0
  56. package/src/shacl/SHACLFlow.test.ts +762 -35
  57. package/src/shacl/SHACLFlow.ts +680 -112
  58. package/src/shacl/SHACLShape.ts +31 -0
  59. package/lib/src/generated/rest/AIModelLoadingStatus.d.ts +0 -7
  60. package/lib/src/generated/rest/AIModelLoadingStatus.js +0 -2
  61. package/lib/src/generated/rest/AddAgentInfosRequest.d.ts +0 -3
  62. package/lib/src/generated/rest/AddAgentInfosRequest.js +0 -2
  63. package/lib/src/generated/rest/AddLinkExpressionRequest.d.ts +0 -6
  64. package/lib/src/generated/rest/AddLinkExpressionRequest.js +0 -1
  65. package/lib/src/generated/rest/AddLinkRequest.d.ts +0 -6
  66. package/lib/src/generated/rest/AddLinkRequest.js +0 -1
  67. package/lib/src/generated/rest/AddLinksBulkRequest.d.ts +0 -6
  68. package/lib/src/generated/rest/AddLinksBulkRequest.js +0 -1
  69. package/lib/src/generated/rest/AddSdnaRequest.d.ts +0 -6
  70. package/lib/src/generated/rest/AddSdnaRequest.js +0 -2
  71. package/lib/src/generated/rest/ApplyTemplateRequest.d.ts +0 -4
  72. package/lib/src/generated/rest/ApplyTemplateRequest.js +0 -2
  73. package/lib/src/generated/rest/AuthInfoInput.d.ts +0 -10
  74. package/lib/src/generated/rest/AuthInfoInput.js +0 -1
  75. package/lib/src/generated/rest/BroadcastRequest.d.ts +0 -6
  76. package/lib/src/generated/rest/BroadcastRequest.js +0 -1
  77. package/lib/src/generated/rest/CapabilityInput.d.ts +0 -5
  78. package/lib/src/generated/rest/CapabilityInput.js +0 -1
  79. package/lib/src/generated/rest/CommitBatchRequest.d.ts +0 -3
  80. package/lib/src/generated/rest/CommitBatchRequest.js +0 -2
  81. package/lib/src/generated/rest/ComputeLogEntry.d.ts +0 -9
  82. package/lib/src/generated/rest/ComputeLogEntry.js +0 -2
  83. package/lib/src/generated/rest/CreateExpressionRequest.d.ts +0 -4
  84. package/lib/src/generated/rest/CreateExpressionRequest.js +0 -2
  85. package/lib/src/generated/rest/CreatePerspectiveRequest.d.ts +0 -3
  86. package/lib/src/generated/rest/CreatePerspectiveRequest.js +0 -2
  87. package/lib/src/generated/rest/CreateSubjectRequest.d.ts +0 -6
  88. package/lib/src/generated/rest/CreateSubjectRequest.js +0 -2
  89. package/lib/src/generated/rest/CreateUserRequest.d.ts +0 -4
  90. package/lib/src/generated/rest/CreateUserRequest.js +0 -2
  91. package/lib/src/generated/rest/CreateUserResponse.d.ts +0 -5
  92. package/lib/src/generated/rest/CreateUserResponse.js +0 -2
  93. package/lib/src/generated/rest/DecoratedExpressionProof.d.ts +0 -6
  94. package/lib/src/generated/rest/DecoratedExpressionProof.js +0 -2
  95. package/lib/src/generated/rest/DecoratedLinkExpression.d.ts +0 -10
  96. package/lib/src/generated/rest/DecoratedLinkExpression.js +0 -1
  97. package/lib/src/generated/rest/DisposeQueryRequest.d.ts +0 -3
  98. package/lib/src/generated/rest/DisposeQueryRequest.js +0 -2
  99. package/lib/src/generated/rest/EmailTestRequest.d.ts +0 -6
  100. package/lib/src/generated/rest/EmailTestRequest.js +0 -2
  101. package/lib/src/generated/rest/EmbedRequest.d.ts +0 -4
  102. package/lib/src/generated/rest/EmbedRequest.js +0 -2
  103. package/lib/src/generated/rest/EntanglementProofInput.d.ts +0 -6
  104. package/lib/src/generated/rest/EntanglementProofInput.js +0 -2
  105. package/lib/src/generated/rest/EntanglementProofPreflightRequest.d.ts +0 -4
  106. package/lib/src/generated/rest/EntanglementProofPreflightRequest.js +0 -2
  107. package/lib/src/generated/rest/ExecuteCommandsRequest.d.ts +0 -4
  108. package/lib/src/generated/rest/ExecuteCommandsRequest.js +0 -2
  109. package/lib/src/generated/rest/ExportRequest.d.ts +0 -5
  110. package/lib/src/generated/rest/ExportRequest.js +0 -2
  111. package/lib/src/generated/rest/ExpressionManyRequest.d.ts +0 -3
  112. package/lib/src/generated/rest/ExpressionManyRequest.js +0 -2
  113. package/lib/src/generated/rest/ExpressionProof.d.ts +0 -4
  114. package/lib/src/generated/rest/ExpressionProof.js +0 -2
  115. package/lib/src/generated/rest/ExpressionProofInput.d.ts +0 -6
  116. package/lib/src/generated/rest/ExpressionProofInput.js +0 -2
  117. package/lib/src/generated/rest/FriendSendMessageRequest.d.ts +0 -3
  118. package/lib/src/generated/rest/FriendSendMessageRequest.js +0 -2
  119. package/lib/src/generated/rest/FriendsListRequest.d.ts +0 -3
  120. package/lib/src/generated/rest/FriendsListRequest.js +0 -2
  121. package/lib/src/generated/rest/GenerateAgentRequest.d.ts +0 -3
  122. package/lib/src/generated/rest/GenerateAgentRequest.js +0 -2
  123. package/lib/src/generated/rest/GenerateJwtRequest.d.ts +0 -4
  124. package/lib/src/generated/rest/GenerateJwtRequest.js +0 -2
  125. package/lib/src/generated/rest/GetSubjectDataRequest.d.ts +0 -4
  126. package/lib/src/generated/rest/GetSubjectDataRequest.js +0 -2
  127. package/lib/src/generated/rest/HostingInfoResponse.d.ts +0 -5
  128. package/lib/src/generated/rest/HostingInfoResponse.js +0 -2
  129. package/lib/src/generated/rest/HostingWalletResponse.d.ts +0 -4
  130. package/lib/src/generated/rest/HostingWalletResponse.js +0 -2
  131. package/lib/src/generated/rest/ImportAgentRequest.d.ts +0 -6
  132. package/lib/src/generated/rest/ImportAgentRequest.js +0 -2
  133. package/lib/src/generated/rest/ImportRequest.d.ts +0 -4
  134. package/lib/src/generated/rest/ImportRequest.js +0 -2
  135. package/lib/src/generated/rest/JoinNeighbourhoodRequest.d.ts +0 -3
  136. package/lib/src/generated/rest/JoinNeighbourhoodRequest.js +0 -2
  137. package/lib/src/generated/rest/KeepAliveQueryRequest.d.ts +0 -3
  138. package/lib/src/generated/rest/KeepAliveQueryRequest.js +0 -2
  139. package/lib/src/generated/rest/LanguageMetaInput.d.ts +0 -6
  140. package/lib/src/generated/rest/LanguageMetaInput.js +0 -2
  141. package/lib/src/generated/rest/Link.d.ts +0 -5
  142. package/lib/src/generated/rest/Link.js +0 -2
  143. package/lib/src/generated/rest/LinkExpression.d.ts +0 -10
  144. package/lib/src/generated/rest/LinkExpression.js +0 -1
  145. package/lib/src/generated/rest/LinkExpressionInput.d.ts +0 -10
  146. package/lib/src/generated/rest/LinkExpressionInput.js +0 -1
  147. package/lib/src/generated/rest/LinkInput.d.ts +0 -5
  148. package/lib/src/generated/rest/LinkInput.js +0 -2
  149. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.d.ts +0 -3
  150. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.js +0 -2
  151. package/lib/src/generated/rest/LinkMutationRequest.d.ts +0 -12
  152. package/lib/src/generated/rest/LinkMutationRequest.js +0 -1
  153. package/lib/src/generated/rest/LinkMutationResponse.d.ts +0 -9
  154. package/lib/src/generated/rest/LinkMutationResponse.js +0 -1
  155. package/lib/src/generated/rest/LinkMutations.d.ts +0 -6
  156. package/lib/src/generated/rest/LinkMutations.js +0 -1
  157. package/lib/src/generated/rest/LinkMutationsRequest.d.ts +0 -5
  158. package/lib/src/generated/rest/LinkMutationsRequest.js +0 -1
  159. package/lib/src/generated/rest/LinkStatus.d.ts +0 -1
  160. package/lib/src/generated/rest/LinkStatus.js +0 -2
  161. package/lib/src/generated/rest/LinkUpdateInput.d.ts +0 -5
  162. package/lib/src/generated/rest/LinkUpdateInput.js +0 -1
  163. package/lib/src/generated/rest/LockAgentRequest.d.ts +0 -3
  164. package/lib/src/generated/rest/LockAgentRequest.js +0 -2
  165. package/lib/src/generated/rest/LoginUserRequest.d.ts +0 -5
  166. package/lib/src/generated/rest/LoginUserRequest.js +0 -2
  167. package/lib/src/generated/rest/ModelType.d.ts +0 -1
  168. package/lib/src/generated/rest/ModelType.js +0 -2
  169. package/lib/src/generated/rest/NotificationGrantRequest.d.ts +0 -3
  170. package/lib/src/generated/rest/NotificationGrantRequest.js +0 -2
  171. package/lib/src/generated/rest/NotificationInput.d.ts +0 -10
  172. package/lib/src/generated/rest/NotificationInput.js +0 -2
  173. package/lib/src/generated/rest/OpenLinkRequest.d.ts +0 -3
  174. package/lib/src/generated/rest/OpenLinkRequest.js +0 -2
  175. package/lib/src/generated/rest/PermitCapabilityRequest.d.ts +0 -3
  176. package/lib/src/generated/rest/PermitCapabilityRequest.js +0 -2
  177. package/lib/src/generated/rest/PerspectiveInput.d.ts +0 -4
  178. package/lib/src/generated/rest/PerspectiveInput.js +0 -1
  179. package/lib/src/generated/rest/PromptRequest.d.ts +0 -4
  180. package/lib/src/generated/rest/PromptRequest.js +0 -2
  181. package/lib/src/generated/rest/PublicPerspectiveInput.d.ts +0 -4
  182. package/lib/src/generated/rest/PublicPerspectiveInput.js +0 -1
  183. package/lib/src/generated/rest/PublishLanguageRequest.d.ts +0 -5
  184. package/lib/src/generated/rest/PublishLanguageRequest.js +0 -1
  185. package/lib/src/generated/rest/PublishNeighbourhoodRequest.d.ts +0 -6
  186. package/lib/src/generated/rest/PublishNeighbourhoodRequest.js +0 -1
  187. package/lib/src/generated/rest/QueryRequest.d.ts +0 -7
  188. package/lib/src/generated/rest/QueryRequest.js +0 -2
  189. package/lib/src/generated/rest/RemoveLinkRequest.d.ts +0 -5
  190. package/lib/src/generated/rest/RemoveLinkRequest.js +0 -1
  191. package/lib/src/generated/rest/RemoveLinksBulkRequest.d.ts +0 -5
  192. package/lib/src/generated/rest/RemoveLinksBulkRequest.js +0 -1
  193. package/lib/src/generated/rest/RequestCapabilityRequest.d.ts +0 -4
  194. package/lib/src/generated/rest/RequestCapabilityRequest.js +0 -1
  195. package/lib/src/generated/rest/RequestPaymentRequest.d.ts +0 -3
  196. package/lib/src/generated/rest/RequestPaymentRequest.js +0 -2
  197. package/lib/src/generated/rest/RequestVerificationRequest.d.ts +0 -4
  198. package/lib/src/generated/rest/RequestVerificationRequest.js +0 -2
  199. package/lib/src/generated/rest/ResourceInput.d.ts +0 -4
  200. package/lib/src/generated/rest/ResourceInput.js +0 -2
  201. package/lib/src/generated/rest/SetDefaultModelRequest.d.ts +0 -4
  202. package/lib/src/generated/rest/SetDefaultModelRequest.js +0 -1
  203. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.d.ts +0 -3
  204. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.js +0 -2
  205. package/lib/src/generated/rest/SetHotWalletAddressRequest.d.ts +0 -3
  206. package/lib/src/generated/rest/SetHotWalletAddressRequest.js +0 -2
  207. package/lib/src/generated/rest/SetMultiUserRequest.d.ts +0 -3
  208. package/lib/src/generated/rest/SetMultiUserRequest.js +0 -2
  209. package/lib/src/generated/rest/SetOnlineStatusRequest.d.ts +0 -5
  210. package/lib/src/generated/rest/SetOnlineStatusRequest.js +0 -1
  211. package/lib/src/generated/rest/SetStatusRequest.d.ts +0 -3
  212. package/lib/src/generated/rest/SetStatusRequest.js +0 -2
  213. package/lib/src/generated/rest/SetUserFreeAccessRequest.d.ts +0 -4
  214. package/lib/src/generated/rest/SetUserFreeAccessRequest.js +0 -2
  215. package/lib/src/generated/rest/SignMessageRequest.d.ts +0 -3
  216. package/lib/src/generated/rest/SignMessageRequest.js +0 -2
  217. package/lib/src/generated/rest/SignalRequest.d.ts +0 -6
  218. package/lib/src/generated/rest/SignalRequest.js +0 -1
  219. package/lib/src/generated/rest/SubscribeQueryRequest.d.ts +0 -3
  220. package/lib/src/generated/rest/SubscribeQueryRequest.js +0 -2
  221. package/lib/src/generated/rest/SubscribeQueryResponse.d.ts +0 -4
  222. package/lib/src/generated/rest/SubscribeQueryResponse.js +0 -2
  223. package/lib/src/generated/rest/TrustedAgentsRequest.d.ts +0 -3
  224. package/lib/src/generated/rest/TrustedAgentsRequest.js +0 -2
  225. package/lib/src/generated/rest/UnlockAgentRequest.d.ts +0 -4
  226. package/lib/src/generated/rest/UnlockAgentRequest.js +0 -2
  227. package/lib/src/generated/rest/UpdateLinkRequest.d.ts +0 -7
  228. package/lib/src/generated/rest/UpdateLinkRequest.js +0 -1
  229. package/lib/src/generated/rest/UpdatePerspectiveRequest.d.ts +0 -3
  230. package/lib/src/generated/rest/UpdatePerspectiveRequest.js +0 -2
  231. package/lib/src/generated/rest/UpdateProfileRequest.d.ts +0 -5
  232. package/lib/src/generated/rest/UpdateProfileRequest.js +0 -1
  233. package/lib/src/generated/rest/UserStatistics.d.ts +0 -9
  234. package/lib/src/generated/rest/UserStatistics.js +0 -2
  235. package/lib/src/generated/rest/VerificationRequestResult.d.ts +0 -6
  236. package/lib/src/generated/rest/VerificationRequestResult.js +0 -2
  237. package/lib/src/generated/rest/VerifyEmailRequest.d.ts +0 -6
  238. package/lib/src/generated/rest/VerifyEmailRequest.js +0 -2
  239. package/lib/src/generated/rest/VerifySignatureRequest.d.ts +0 -5
  240. package/lib/src/generated/rest/VerifySignatureRequest.js +0 -2
  241. package/lib/src/generated/rest/WriteSettingsRequest.d.ts +0 -3
  242. package/lib/src/generated/rest/WriteSettingsRequest.js +0 -2
  243. package/lib/src/generated/rest/index.d.ts +0 -73
  244. package/lib/src/generated/rest/index.js +0 -8
  245. package/lib/src/generated/rest/routes.d.ts +0 -587
  246. package/lib/src/generated/rest/routes.js +0 -3
  247. package/lib/src/model/query-surreal.d.ts +0 -44
  248. package/lib/src/model/query-surreal.js +0 -249
  249. package/lib/src/model/surreal-utils.d.ts +0 -42
  250. package/lib/src/model/surreal-utils.js +0 -128
  251. package/lib/src/perspectives/PerspectiveProxy.test.d.ts +0 -1
  252. package/lib/src/perspectives/PerspectiveProxy.test.js +0 -34
  253. package/lib/src/restClient.d.ts +0 -52
  254. package/lib/src/restClient.js +0 -227
@@ -1,4 +1,6 @@
1
- import { SHACLFlow, FlowState, FlowTransition, AD4MAction } from './SHACLFlow';
1
+ import { SHACLFlow, FlowState, FlowTransition, AD4MAction, ConsensusRule } from './SHACLFlow';
2
+ import { Link } from '../links/Links';
3
+ import { Literal } from '../Literal';
2
4
 
3
5
  describe('SHACLFlow', () => {
4
6
  describe('basic construction', () => {
@@ -28,13 +30,11 @@ describe('SHACLFlow', () => {
28
30
  flow.addState({
29
31
  name: 'ready',
30
32
  value: 0,
31
- stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
32
33
  });
33
34
 
34
35
  flow.addState({
35
36
  name: 'done',
36
37
  value: 1,
37
- stateCheck: { predicate: 'todo://state', target: 'todo://done' }
38
38
  });
39
39
 
40
40
  expect(flow.states.length).toBe(2);
@@ -66,15 +66,9 @@ describe('SHACLFlow', () => {
66
66
  describe('toLinks()', () => {
67
67
  it('serializes flow to links', () => {
68
68
  const flow = new SHACLFlow('TODO', 'todo://');
69
- flow.flowable = 'any';
70
- flow.startAction = [
71
- { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
72
- ];
73
-
74
69
  flow.addState({
75
70
  name: 'ready',
76
71
  value: 0,
77
- stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
78
72
  });
79
73
 
80
74
  flow.addTransition({
@@ -91,15 +85,11 @@ describe('SHACLFlow', () => {
91
85
  expect(typeLink).toBeDefined();
92
86
  expect(typeLink!.source).toBe('todo://TODOFlow');
93
87
 
94
- // Check flowable link
88
+ // `flowable` retired (design §4.1) — the flow serializer must not emit
89
+ // any `ad4m://flowable` link. `inputTypes` is the successor field and
90
+ // gets exercised separately.
95
91
  const flowableLink = links.find(l => l.predicate === 'ad4m://flowable');
96
- expect(flowableLink).toBeDefined();
97
- expect(flowableLink!.target).toBe('ad4m://any');
98
-
99
- // Check start action link
100
- const startActionLink = links.find(l => l.predicate === 'ad4m://startAction');
101
- expect(startActionLink).toBeDefined();
102
- expect(startActionLink!.target).toContain('addLink');
92
+ expect(flowableLink).toBeUndefined();
103
93
 
104
94
  // Check state link
105
95
  const stateLink = links.find(l => l.predicate === 'ad4m://hasState');
@@ -115,19 +105,13 @@ describe('SHACLFlow', () => {
115
105
  describe('fromLinks()', () => {
116
106
  it('reconstructs flow from links', () => {
117
107
  const original = new SHACLFlow('TODO', 'todo://');
118
- original.flowable = 'any';
119
- original.startAction = [
120
- { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
121
- ];
122
108
  original.addState({
123
109
  name: 'ready',
124
110
  value: 0,
125
- stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
126
111
  });
127
112
  original.addState({
128
113
  name: 'done',
129
114
  value: 1,
130
- stateCheck: { predicate: 'todo://state', target: 'todo://done' }
131
115
  });
132
116
  original.addTransition({
133
117
  actionName: 'Complete',
@@ -141,12 +125,34 @@ describe('SHACLFlow', () => {
141
125
 
142
126
  expect(reconstructed.name).toBe('TODO');
143
127
  expect(reconstructed.namespace).toBe('todo://');
144
- expect(reconstructed.flowable).toBe('any');
145
- expect(reconstructed.startAction.length).toBe(1);
146
128
  expect(reconstructed.states.length).toBe(2);
147
129
  expect(reconstructed.transitions.length).toBe(1);
148
130
  expect(reconstructed.transitions[0].actionName).toBe('Complete');
149
131
  });
132
+
133
+ it('sorts states by value so states[0] is the lowest-value (initial) state after a graph round-trip', () => {
134
+ // Perspective link storage does not preserve insertion order — `hasState`
135
+ // links come back arbitrarily, which used to break the "initial state
136
+ // = states[0]" convention that `FlowInstance.start`
137
+ // relies on to mint the first state of a fresh instance.
138
+ const original = new SHACLFlow('Delivery', 'ns://');
139
+ original.addState({ name: 'Identified', value: 0 });
140
+ original.addState({ name: 'InProgress', value: 1 });
141
+ original.addState({ name: 'Done', value: 2 });
142
+
143
+ const links = original.toLinks();
144
+ // Simulate perspective returning `hasState` links out of order (reverse).
145
+ const hasStateLinks = links.filter(l => l.predicate === 'ad4m://hasState');
146
+ const otherLinks = links.filter(l => l.predicate !== 'ad4m://hasState');
147
+ const shuffled = [...otherLinks, ...hasStateLinks.slice().reverse()];
148
+
149
+ const reconstructed = SHACLFlow.fromLinks(shuffled, 'ns://DeliveryFlow');
150
+ expect(reconstructed.states.length).toBe(3);
151
+ expect(reconstructed.states[0].name).toBe('Identified');
152
+ expect(reconstructed.states[1].name).toBe('InProgress');
153
+ expect(reconstructed.states[2].name).toBe('Done');
154
+ expect(reconstructed.states[0].value).toBe(0);
155
+ });
150
156
  });
151
157
 
152
158
  describe('JSON serialization', () => {
@@ -155,7 +161,6 @@ describe('SHACLFlow', () => {
155
161
  original.addState({
156
162
  name: 'ready',
157
163
  value: 0,
158
- stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
159
164
  });
160
165
  original.addTransition({
161
166
  actionName: 'Start',
@@ -176,28 +181,20 @@ describe('SHACLFlow', () => {
176
181
  describe('full TODO example', () => {
177
182
  it('creates complete TODO flow matching Prolog example', () => {
178
183
  const flow = new SHACLFlow('TODO', 'todo://');
179
- flow.flowable = 'any';
180
-
184
+
181
185
  // Start action - renders expression as TODO in 'ready' state
182
- flow.startAction = [
183
- { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
184
- ];
185
-
186
186
  // Three states
187
187
  flow.addState({
188
188
  name: 'ready',
189
189
  value: 0,
190
- stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
191
190
  });
192
191
  flow.addState({
193
192
  name: 'doing',
194
193
  value: 0.5,
195
- stateCheck: { predicate: 'todo://state', target: 'todo://doing' }
196
194
  });
197
195
  flow.addState({
198
196
  name: 'done',
199
197
  value: 1,
200
- stateCheck: { predicate: 'todo://state', target: 'todo://done' }
201
198
  });
202
199
 
203
200
  // Transitions
@@ -234,4 +231,734 @@ describe('SHACLFlow', () => {
234
231
  expect(reconstructed.transitions.length).toBe(2);
235
232
  });
236
233
  });
234
+
235
+ describe('interpretationHint (AI-driven state suggestion)', () => {
236
+ it('round-trips top-level and per-state interpretation hints via toLinks/fromLinks', () => {
237
+ const flow = new SHACLFlow('Deliberation', 'ns://deliberation/');
238
+ flow.interpretationHint =
239
+ 'Tracks a group deliberation from initial proposal to shared understanding.';
240
+
241
+ flow.addState({
242
+ name: 'Proposal',
243
+ value: 0,
244
+ interpretationHint:
245
+ 'The initial proposal or question has been raised. No distinct perspective or objection has been voiced yet.'
246
+ });
247
+ flow.addState({
248
+ name: 'Tension',
249
+ value: 1,
250
+ interpretationHint:
251
+ 'Participants have expressed opposing views or objections — a clear disagreement is on the table.'
252
+ });
253
+ // A state deliberately without an interpretationHint stays hint-free after round-trip.
254
+ flow.addState({
255
+ name: 'Resolution',
256
+ value: 2,
257
+ });
258
+
259
+ const links = flow.toLinks();
260
+ const roundTripped = SHACLFlow.fromLinks(links, flow.flowUri);
261
+
262
+ expect(roundTripped.interpretationHint).toBe(flow.interpretationHint);
263
+ expect(roundTripped.states.find(s => s.name === 'Proposal')?.interpretationHint)
264
+ .toBe(flow.states.find(s => s.name === 'Proposal')?.interpretationHint);
265
+ expect(roundTripped.states.find(s => s.name === 'Tension')?.interpretationHint)
266
+ .toBe(flow.states.find(s => s.name === 'Tension')?.interpretationHint);
267
+ expect(roundTripped.states.find(s => s.name === 'Resolution')?.interpretationHint)
268
+ .toBeUndefined();
269
+ });
270
+
271
+ it('round-trips interpretation hints via toJSON/fromJSON', () => {
272
+ const flow = new SHACLFlow('Deliberation', 'ns://deliberation/');
273
+ flow.interpretationHint = 'Top-level hint.';
274
+ flow.addState({
275
+ name: 'Proposal',
276
+ value: 0,
277
+ interpretationHint: 'Per-state hint.'
278
+ });
279
+
280
+ const json = flow.toJSON() as any;
281
+ expect(json.interpretationHint).toBe('Top-level hint.');
282
+ expect(json.states[0].interpretationHint).toBe('Per-state hint.');
283
+
284
+ const roundTripped = SHACLFlow.fromJSON(json);
285
+ expect(roundTripped.interpretationHint).toBe('Top-level hint.');
286
+ expect(roundTripped.states[0].interpretationHint).toBe('Per-state hint.');
287
+ });
288
+
289
+ it('omits interpretationHint from toJSON when unset (backwards-compatible)', () => {
290
+ const flow = new SHACLFlow('TODO', 'todo://');
291
+ flow.addState({
292
+ name: 'ready',
293
+ value: 0,
294
+ });
295
+
296
+ const json = flow.toJSON() as any;
297
+ expect('interpretationHint' in json).toBe(false);
298
+ // States without a hint don't gain one — existing schema is untouched.
299
+ expect('interpretationHint' in json.states[0]).toBe(false);
300
+ });
301
+ });
302
+
303
+ describe('requires + semanticCheck on FlowState (v1 flow guards)', () => {
304
+ it('round-trips a state with `requires` and `semanticCheck` via toLinks/fromLinks', () => {
305
+ const flow = new SHACLFlow('Deliberation', 'ns://deliberation/');
306
+ flow.addState({
307
+ name: 'Tension',
308
+ value: 1,
309
+ interpretationHint:
310
+ 'Participants have expressed opposing views or objections.',
311
+ // Design §4.1: model-level guard replacing raw-link stateCheck.
312
+ // AND-combined; every entry must match on committed graph state.
313
+ requires: [
314
+ {
315
+ className: 'ns://Objection',
316
+ where: { about: '$flow.base' },
317
+ count: { min: 1 },
318
+ linkedTo: 'base',
319
+ },
320
+ {
321
+ className: 'ns://Perspective',
322
+ where: { about: '$flow.base', stance: { in: ['for', 'against'] } },
323
+ count: { min: 2 },
324
+ },
325
+ ],
326
+ // Design §5: LLM confirmation after `requires` structurally matches.
327
+ semanticCheck:
328
+ 'Confirm the objection is a genuine disagreement, not a clarifying question.',
329
+ });
330
+
331
+ const links = flow.toLinks();
332
+ const roundTripped = SHACLFlow.fromLinks(links, flow.flowUri);
333
+
334
+ const tension = roundTripped.states.find(s => s.name === 'Tension');
335
+ expect(tension).toBeDefined();
336
+ // requires: array preserved, condition shorthands + object forms both survive.
337
+ expect(tension?.requires).toHaveLength(2);
338
+ expect(tension?.requires?.[0].className).toBe('ns://Objection');
339
+ expect(tension?.requires?.[0].where).toEqual({ about: '$flow.base' });
340
+ expect(tension?.requires?.[0].count).toEqual({ min: 1 });
341
+ expect(tension?.requires?.[0].linkedTo).toBe('base');
342
+ expect(tension?.requires?.[1].where).toEqual({
343
+ about: '$flow.base',
344
+ stance: { in: ['for', 'against'] },
345
+ });
346
+ expect(tension?.requires?.[1].count).toEqual({ min: 2 });
347
+ // semanticCheck string round-trips through Literal serialization.
348
+ expect(tension?.semanticCheck).toBe(
349
+ 'Confirm the objection is a genuine disagreement, not a clarifying question.'
350
+ );
351
+ });
352
+
353
+ it('round-trips requires + semanticCheck via toJSON/fromJSON', () => {
354
+ const flow = new SHACLFlow('Delivery', 'ns://delivery/');
355
+ flow.addState({
356
+ name: 'Done',
357
+ value: 1,
358
+ requires: [
359
+ {
360
+ className: 'ns://CompletionEvidence',
361
+ where: { forTask: '$flow.base' },
362
+ count: { min: 1 },
363
+ },
364
+ ],
365
+ semanticCheck: 'Confirm the artifact matches what was asked for.',
366
+ });
367
+
368
+ const json = flow.toJSON() as any;
369
+ const done = json.states[0];
370
+ expect(done.requires).toHaveLength(1);
371
+ expect(done.requires[0].className).toBe('ns://CompletionEvidence');
372
+ expect(done.semanticCheck).toBe('Confirm the artifact matches what was asked for.');
373
+
374
+ const roundTripped = SHACLFlow.fromJSON(json);
375
+ const rtDone = roundTripped.states.find(s => s.name === 'Done');
376
+ expect(rtDone?.requires?.[0].className).toBe('ns://CompletionEvidence');
377
+ expect(rtDone?.requires?.[0].where).toEqual({ forTask: '$flow.base' });
378
+ expect(rtDone?.semanticCheck).toBe('Confirm the artifact matches what was asked for.');
379
+ });
380
+
381
+ it('omits requires and semanticCheck from toLinks when unset (backwards-compatible)', () => {
382
+ // Minimal state — no v1 predicates land on the state URI.
383
+ const flow = new SHACLFlow('TODO', 'todo://');
384
+ flow.addState({
385
+ name: 'ready',
386
+ value: 0,
387
+ });
388
+
389
+ const links = flow.toLinks();
390
+ const stateUri = flow.stateUri('ready');
391
+ const requiresLinks = links.filter(
392
+ l => l.source === stateUri && l.predicate === 'ad4m://requires'
393
+ );
394
+ const semanticCheckLinks = links.filter(
395
+ l => l.source === stateUri && l.predicate === 'ad4m://semanticCheck'
396
+ );
397
+ expect(requiresLinks).toHaveLength(0);
398
+ expect(semanticCheckLinks).toHaveLength(0);
399
+
400
+ // Round-trip: the state's fields stay undefined, not empty objects.
401
+ const roundTripped = SHACLFlow.fromLinks(links, flow.flowUri);
402
+ const ready = roundTripped.states.find(s => s.name === 'ready');
403
+ expect(ready?.requires).toBeUndefined();
404
+ expect(ready?.semanticCheck).toBeUndefined();
405
+ });
406
+
407
+ it('an empty `requires` array is treated as no guard (no link emitted)', () => {
408
+ const flow = new SHACLFlow('Empty', 'ns://empty/');
409
+ flow.addState({
410
+ name: 'x',
411
+ value: 0,
412
+ requires: [],
413
+ });
414
+
415
+ const links = flow.toLinks();
416
+ const stateUri = flow.stateUri('x');
417
+ const requiresLinks = links.filter(
418
+ l => l.source === stateUri && l.predicate === 'ad4m://requires'
419
+ );
420
+ expect(requiresLinks).toHaveLength(0);
421
+ });
422
+ });
423
+
424
+ describe('CodeRabbit hardening: empty-string / malformed-value tolerance', () => {
425
+ it('empty-string interpretationHint / semanticCheck emit zero predicates', () => {
426
+ // Empty strings must be treated as "unset" so we don't materialise an
427
+ // empty-hint predicate that a consumer would read back as a meaningful
428
+ // value (CodeRabbit PR #929 comment on lines 316-323 / 388-395 / 408-416).
429
+ // Same rule must apply to json.states[i] so JSON and toLinks agree on
430
+ // "unset" (CodeRabbit PR #929 follow-up on lines 891-907).
431
+ const flow = new SHACLFlow('Empty', 'ns://empty/');
432
+ flow.interpretationHint = '';
433
+ flow.addState({
434
+ name: 'x',
435
+ value: 0,
436
+ interpretationHint: '',
437
+ semanticCheck: '',
438
+ requires: [],
439
+ });
440
+
441
+ const links = flow.toLinks();
442
+ const hintLinks = links.filter(l => l.predicate === 'ad4m://interpretationHint');
443
+ const semanticCheckLinks = links.filter(l => l.predicate === 'ad4m://semanticCheck');
444
+ const requiresLinks = links.filter(l => l.predicate === 'ad4m://requires');
445
+ expect(hintLinks).toHaveLength(0);
446
+ expect(semanticCheckLinks).toHaveLength(0);
447
+ expect(requiresLinks).toHaveLength(0);
448
+
449
+ const json = flow.toJSON() as any;
450
+ expect('interpretationHint' in json).toBe(false);
451
+ // json.states[0] must strip the same optional fields as toLinks does.
452
+ expect('interpretationHint' in json.states[0]).toBe(false);
453
+ expect('semanticCheck' in json.states[0]).toBe(false);
454
+ expect('requires' in json.states[0]).toBe(false);
455
+ // Required fields still present.
456
+ expect(json.states[0].name).toBe('x');
457
+ expect(json.states[0].value).toBe(0);
458
+ });
459
+
460
+ it('malformed decoded literals leave the field unset (fromLinks)', () => {
461
+ // Simulate a broken graph: the ad4m://interpretationHint link points at
462
+ // a target that decodes to a non-string via Literal.get(). The reader
463
+ // must not blindly `as string`-cast it into flow metadata.
464
+ const flow = new SHACLFlow('Deliberation', 'ns://deliberation/');
465
+ flow.addState({
466
+ name: 'Proposal',
467
+ value: 0,
468
+ });
469
+
470
+ const links = flow.toLinks();
471
+ const flowUri = flow.flowUri;
472
+ const stateUri = flow.stateUri('Proposal');
473
+
474
+ // Non-string literals: literal:number decodes to a real number,
475
+ // literal:json to a real object. `Literal.get()` returns the decoded
476
+ // typed value, so a naive `as string` cast would leak them into flow
477
+ // metadata unless the reader validates.
478
+ const nonStringNumber = `literal:number:${encodeURIComponent('42')}`;
479
+ const nonStringObject = `literal:json:${encodeURIComponent(JSON.stringify({ evil: true }))}`;
480
+
481
+ links.push({
482
+ source: flowUri,
483
+ predicate: 'ad4m://interpretationHint',
484
+ target: nonStringNumber,
485
+ });
486
+ links.push({
487
+ source: stateUri,
488
+ predicate: 'ad4m://interpretationHint',
489
+ target: nonStringObject,
490
+ });
491
+ links.push({
492
+ source: stateUri,
493
+ predicate: 'ad4m://semanticCheck',
494
+ target: nonStringNumber,
495
+ });
496
+
497
+ const roundTripped = SHACLFlow.fromLinks(links, flowUri);
498
+ const proposal = roundTripped.states.find(s => s.name === 'Proposal');
499
+ expect(roundTripped.interpretationHint).toBeUndefined();
500
+ expect(proposal?.interpretationHint).toBeUndefined();
501
+ expect(proposal?.semanticCheck).toBeUndefined();
502
+ });
503
+
504
+ it('malformed `requires` array entries leave the guard unset (fromLinks)', () => {
505
+ // Array.isArray alone accepts `[null]` / `[{}]` / `[42]` — a broken
506
+ // graph should not materialise those as ModelQuery entries.
507
+ const flow = new SHACLFlow('Deliberation', 'ns://deliberation/');
508
+ flow.addState({
509
+ name: 'Tension',
510
+ value: 1,
511
+ });
512
+
513
+ const links = flow.toLinks();
514
+ const stateUri = flow.stateUri('Tension');
515
+
516
+ // Case 1: array with null entry.
517
+ const bogus1 = `literal:string:${encodeURIComponent(JSON.stringify([null]))}`;
518
+ // Case 2: array with empty object (no className).
519
+ const bogus2 = `literal:string:${encodeURIComponent(JSON.stringify([{}]))}`;
520
+ // Case 3: array with entry whose className is not a string.
521
+ const bogus3 = `literal:string:${encodeURIComponent(JSON.stringify([{ className: 42 }]))}`;
522
+ // Case 4: array with entry whose className is empty string.
523
+ const bogus4 = `literal:string:${encodeURIComponent(JSON.stringify([{ className: '' }]))}`;
524
+
525
+ for (const bogus of [bogus1, bogus2, bogus3, bogus4]) {
526
+ const brokenLinks = [
527
+ ...links,
528
+ { source: stateUri, predicate: 'ad4m://requires', target: bogus },
529
+ ];
530
+ const rt = SHACLFlow.fromLinks(brokenLinks, flow.flowUri);
531
+ expect(rt.states.find(s => s.name === 'Tension')?.requires).toBeUndefined();
532
+ }
533
+
534
+ // Sanity: a well-shaped entry mixed in a valid array still round-trips.
535
+ const good = `literal:string:${encodeURIComponent(
536
+ JSON.stringify([{ className: 'ns://Objection', where: { about: '$flow.base' } }])
537
+ )}`;
538
+ const goodLinks = [
539
+ ...links,
540
+ { source: stateUri, predicate: 'ad4m://requires', target: good },
541
+ ];
542
+ const rtGood = SHACLFlow.fromLinks(goodLinks, flow.flowUri);
543
+ expect(rtGood.states.find(s => s.name === 'Tension')?.requires).toHaveLength(1);
544
+ expect(rtGood.states.find(s => s.name === 'Tension')?.requires?.[0].className).toBe(
545
+ 'ns://Objection'
546
+ );
547
+ });
548
+
549
+ it('malformed JSON payload sanitisation (fromJSON)', () => {
550
+ // A downstream caller reconstructing from an untrusted JSON blob must
551
+ // get the same non-empty-string / ModelQuery-shape guard as fromLinks.
552
+ const dodgyJson = {
553
+ name: 'Bad',
554
+ namespace: 'ns://bad/',
555
+ interpretationHint: '',
556
+ states: [
557
+ {
558
+ name: 's',
559
+ value: 0,
560
+ interpretationHint: '',
561
+ requires: [null, {}, { className: 42 }],
562
+ semanticCheck: '',
563
+ },
564
+ ],
565
+ transitions: [],
566
+ };
567
+
568
+ const flow = SHACLFlow.fromJSON(dodgyJson);
569
+ expect(flow.interpretationHint).toBeUndefined();
570
+ const s = flow.states.find(x => x.name === 's');
571
+ expect(s?.interpretationHint).toBeUndefined();
572
+ expect(s?.requires).toBeUndefined();
573
+ expect(s?.semanticCheck).toBeUndefined();
574
+ });
575
+ });
576
+
577
+ describe('flow-level typed I/O + creationHint + context (design §4.1)', () => {
578
+ it('round-trips inputTypes / outputTypes / creationHint / context via toLinks/fromLinks', () => {
579
+ const flow = new SHACLFlow('Delivery', 'coasys://');
580
+ flow.inputTypes = ['coasys://Task'];
581
+ flow.outputTypes = ['coasys://Delivery'];
582
+ flow.creationHint =
583
+ 'Spawn when someone commits to a concrete, actionable task.';
584
+ flow.context = [
585
+ {
586
+ className: 'coasys://Actor',
587
+ where: { did: '$did' },
588
+ count: { min: 1 },
589
+ },
590
+ ];
591
+
592
+ const links = flow.toLinks();
593
+ const roundTripped = SHACLFlow.fromLinks(links, flow.flowUri);
594
+ expect(roundTripped.inputTypes).toEqual(['coasys://Task']);
595
+ expect(roundTripped.outputTypes).toEqual(['coasys://Delivery']);
596
+ expect(roundTripped.creationHint).toBe(
597
+ 'Spawn when someone commits to a concrete, actionable task.'
598
+ );
599
+ expect(roundTripped.context).toEqual([
600
+ {
601
+ className: 'coasys://Actor',
602
+ where: { did: '$did' },
603
+ count: { min: 1 },
604
+ },
605
+ ]);
606
+ });
607
+
608
+ it('round-trips a zero-state action flow (Like example, §6.3)', () => {
609
+ const like = new SHACLFlow('Like', 'we://');
610
+ like.inputTypes = ['we://Post'];
611
+ like.outputTypes = ['we://Like'];
612
+ like.creationHint = 'Spawn when a user endorses or approves a post.';
613
+
614
+ const links = like.toLinks();
615
+ const roundTripped = SHACLFlow.fromLinks(links, like.flowUri);
616
+ expect(roundTripped.states).toEqual([]);
617
+ expect(roundTripped.transitions).toEqual([]);
618
+ expect(roundTripped.inputTypes).toEqual(['we://Post']);
619
+ expect(roundTripped.outputTypes).toEqual(['we://Like']);
620
+ expect(roundTripped.creationHint).toBe(
621
+ 'Spawn when a user endorses or approves a post.'
622
+ );
623
+ });
624
+
625
+ it('round-trips inputTypes / outputTypes / creationHint / context via toJSON/fromJSON', () => {
626
+ const flow = new SHACLFlow('Delib', 'coasys://');
627
+ flow.inputTypes = ['coasys://Proposal'];
628
+ flow.outputTypes = ['coasys://Resolution'];
629
+ flow.creationHint = 'Spawn when a proposal is put forward for discussion.';
630
+ flow.context = [
631
+ { className: 'coasys://Group', linkedTo: 'base' },
632
+ ];
633
+
634
+ const json = JSON.parse(JSON.stringify(flow.toJSON()));
635
+ const roundTripped = SHACLFlow.fromJSON(json);
636
+ expect(roundTripped.inputTypes).toEqual(['coasys://Proposal']);
637
+ expect(roundTripped.outputTypes).toEqual(['coasys://Resolution']);
638
+ expect(roundTripped.creationHint).toBe(
639
+ 'Spawn when a proposal is put forward for discussion.'
640
+ );
641
+ expect(roundTripped.context).toEqual([
642
+ { className: 'coasys://Group', linkedTo: 'base' },
643
+ ]);
644
+ });
645
+
646
+ it('omits the new fields from toLinks / toJSON when unset (backwards-compatible)', () => {
647
+ const flow = new SHACLFlow('Bare', 'ns://');
648
+ const links = flow.toLinks();
649
+ expect(
650
+ links.find(l => l.predicate === 'ad4m://inputTypes')
651
+ ).toBeUndefined();
652
+ expect(
653
+ links.find(l => l.predicate === 'ad4m://outputTypes')
654
+ ).toBeUndefined();
655
+ expect(
656
+ links.find(l => l.predicate === 'ad4m://creationHint')
657
+ ).toBeUndefined();
658
+ expect(
659
+ links.find(l => l.predicate === 'ad4m://context')
660
+ ).toBeUndefined();
661
+
662
+ const json = flow.toJSON() as Record<string, unknown>;
663
+ expect(json.inputTypes).toBeUndefined();
664
+ expect(json.outputTypes).toBeUndefined();
665
+ expect(json.creationHint).toBeUndefined();
666
+ expect(json.context).toBeUndefined();
667
+ });
668
+
669
+ it('malformed inputTypes / outputTypes / context leave defaults untouched (fromLinks)', () => {
670
+ const flowUri = 'ns://BadFlow';
671
+ const badLinks: Link[] = [
672
+ { source: flowUri, predicate: 'rdf://type', target: 'ad4m://Flow' },
673
+ {
674
+ source: flowUri,
675
+ predicate: 'ad4m://flowName',
676
+ target: Literal.from('BadFlow').toUrl(),
677
+ },
678
+ {
679
+ source: flowUri,
680
+ predicate: 'ad4m://inputTypes',
681
+ target: `literal:string:${encodeURIComponent(JSON.stringify([null, 42, {}]))}`,
682
+ },
683
+ {
684
+ source: flowUri,
685
+ predicate: 'ad4m://outputTypes',
686
+ target: `literal:string:${encodeURIComponent(JSON.stringify(['', 'coasys://Delivery']))}`,
687
+ },
688
+ {
689
+ source: flowUri,
690
+ predicate: 'ad4m://context',
691
+ target: `literal:string:${encodeURIComponent(JSON.stringify([{ notAClassName: 'x' }]))}`,
692
+ },
693
+ ];
694
+
695
+ const flow = SHACLFlow.fromLinks(badLinks, flowUri);
696
+ expect(flow.inputTypes).toEqual([]);
697
+ expect(flow.outputTypes).toEqual([]);
698
+ expect(flow.context).toBeUndefined();
699
+ });
700
+
701
+ it('malformed inputTypes / outputTypes / creationHint / context sanitised (fromJSON)', () => {
702
+ const dodgyJson = {
703
+ name: 'BadFlow',
704
+ namespace: 'ns://',
705
+ inputTypes: ['coasys://Task', null, 42],
706
+ outputTypes: 'not-an-array',
707
+ creationHint: '',
708
+ context: [{ className: 42 }, null],
709
+ states: [],
710
+ transitions: [],
711
+ };
712
+
713
+ const flow = SHACLFlow.fromJSON(dodgyJson);
714
+ expect(flow.inputTypes).toEqual([]);
715
+ expect(flow.outputTypes).toEqual([]);
716
+ expect(flow.creationHint).toBeUndefined();
717
+ expect(flow.context).toBeUndefined();
718
+ });
719
+ });
720
+
721
+ describe('consensusRule (design §7)', () => {
722
+ it('round-trips a flow-level consensusRule via toLinks/fromLinks', () => {
723
+ const like = new SHACLFlow('Like', 'we://');
724
+ like.inputTypes = ['we://Post'];
725
+ like.outputTypes = ['we://Like'];
726
+ like.consensusRule = { n: 1 };
727
+
728
+ const links = like.toLinks();
729
+ const consensusLink = links.find(
730
+ l => l.source === like.flowUri && l.predicate === 'ad4m://consensusRule'
731
+ );
732
+ expect(consensusLink).toBeDefined();
733
+
734
+ const roundTripped = SHACLFlow.fromLinks(links, like.flowUri);
735
+ expect(roundTripped.consensusRule).toEqual({ n: 1 });
736
+ });
737
+
738
+ it('round-trips a per-state consensusRule override via toLinks/fromLinks', () => {
739
+ const delib = new SHACLFlow('Delib', 'coasys://');
740
+ delib.addState({
741
+ name: 'perspective',
742
+ value: 0.25,
743
+ consensusRule: { n: 1 },
744
+ });
745
+ delib.addState({
746
+ name: 'resolution',
747
+ value: 1,
748
+ consensusRule: {
749
+ n: 2,
750
+ fromRole: {
751
+ className: 'coasys://Reviewer',
752
+ where: { forTask: '$flow.base' },
753
+ didProperty: 'agent',
754
+ },
755
+ },
756
+ });
757
+
758
+ const links = delib.toLinks();
759
+ const roundTripped = SHACLFlow.fromLinks(links, delib.flowUri);
760
+ expect(roundTripped.states[0].consensusRule).toEqual({ n: 1 });
761
+ expect(roundTripped.states[1].consensusRule).toEqual({
762
+ n: 2,
763
+ fromRole: {
764
+ className: 'coasys://Reviewer',
765
+ where: { forTask: '$flow.base' },
766
+ didProperty: 'agent',
767
+ },
768
+ });
769
+ });
770
+
771
+ it('round-trips flow-level + per-state consensusRule via toJSON/fromJSON', () => {
772
+ const flow = new SHACLFlow('Delib', 'coasys://');
773
+ flow.consensusRule = { n: 3 };
774
+ flow.addState({
775
+ name: 'overlap',
776
+ value: 0.75,
777
+ consensusRule: {
778
+ n: 1,
779
+ fromRole: {
780
+ or: [
781
+ { className: 'coasys://Reviewer', didProperty: 'agent' },
782
+ { className: 'coasys://Admin', didProperty: 'agent' },
783
+ ],
784
+ className: 'coasys://Facilitator',
785
+ didProperty: 'agent',
786
+ },
787
+ },
788
+ });
789
+
790
+ const json = JSON.parse(JSON.stringify(flow.toJSON()));
791
+ const roundTripped = SHACLFlow.fromJSON(json);
792
+ expect(roundTripped.consensusRule).toEqual({ n: 3 });
793
+ expect(roundTripped.states[0].consensusRule?.n).toBe(1);
794
+ expect(roundTripped.states[0].consensusRule?.fromRole?.or?.length).toBe(2);
795
+ expect(roundTripped.states[0].consensusRule?.fromRole?.didProperty).toBe('agent');
796
+ });
797
+
798
+ it('omits consensusRule from toLinks / toJSON when unset (backwards-compatible)', () => {
799
+ const flow = new SHACLFlow('Bare', 'ns://');
800
+ flow.addState({
801
+ name: 'ready',
802
+ value: 0,
803
+ });
804
+
805
+ const links = flow.toLinks();
806
+ expect(
807
+ links.find(l => l.predicate === 'ad4m://consensusRule')
808
+ ).toBeUndefined();
809
+
810
+ const json = flow.toJSON() as Record<string, unknown>;
811
+ expect(json.consensusRule).toBeUndefined();
812
+ const states = json.states as Array<Record<string, unknown>>;
813
+ expect(states[0].consensusRule).toBeUndefined();
814
+ });
815
+
816
+ it('rejects malformed consensusRule (missing n, non-integer, bad fromRole) — fromLinks', () => {
817
+ const flowUri = 'ns://BadFlow';
818
+ const stateUri = 'ns://BadFlow.bad';
819
+ const badLinks: Link[] = [
820
+ { source: flowUri, predicate: 'rdf://type', target: 'ad4m://Flow' },
821
+ { source: flowUri, predicate: 'ad4m://flowName', target: Literal.from('BadFlow').toUrl() },
822
+ // Flow-level: missing `n`
823
+ {
824
+ source: flowUri,
825
+ predicate: 'ad4m://consensusRule',
826
+ target: `literal:string:${encodeURIComponent(JSON.stringify({ fromRole: { className: 'ns://R' } }))}`,
827
+ },
828
+ { source: flowUri, predicate: 'ad4m://hasState', target: stateUri },
829
+ { source: stateUri, predicate: 'rdf://type', target: 'ad4m://FlowState' },
830
+ { source: stateUri, predicate: 'ad4m://stateName', target: Literal.from('bad').toUrl() },
831
+ { source: stateUri, predicate: 'ad4m://stateValue', target: Literal.from(0).toUrl() },
832
+ {
833
+ source: stateUri,
834
+ predicate: 'ad4m://stateCheck',
835
+ target: `literal:string:${encodeURIComponent(JSON.stringify({ predicate: 'p', target: 't' }))}`,
836
+ },
837
+ // State-level: non-integer n + junk fromRole
838
+ {
839
+ source: stateUri,
840
+ predicate: 'ad4m://consensusRule',
841
+ target: `literal:string:${encodeURIComponent(JSON.stringify({ n: 'many', fromRole: null }))}`,
842
+ },
843
+ ];
844
+
845
+ const flow = SHACLFlow.fromLinks(badLinks, flowUri);
846
+ expect(flow.consensusRule).toBeUndefined();
847
+ expect(flow.states[0].consensusRule).toBeUndefined();
848
+ });
849
+
850
+ it('rejects malformed consensusRule via fromJSON (n as string, fractional n, fromRole missing className)', () => {
851
+ const dodgyJson = {
852
+ name: 'BadFlow',
853
+ namespace: 'ns://',
854
+ consensusRule: { n: 'many' },
855
+ states: [
856
+ {
857
+ name: 'a',
858
+ value: 0,
859
+ consensusRule: { n: 1.5 },
860
+ },
861
+ {
862
+ name: 'b',
863
+ value: 1,
864
+ consensusRule: { n: 1, fromRole: { where: { x: 1 } } },
865
+ },
866
+ ],
867
+ transitions: [],
868
+ };
869
+
870
+ const flow = SHACLFlow.fromJSON(dodgyJson as any);
871
+ expect(flow.consensusRule).toBeUndefined();
872
+ expect(flow.states[0].consensusRule).toBeUndefined();
873
+ expect(flow.states[1].consensusRule).toBeUndefined();
874
+ });
875
+
876
+ it('rejects malformed `or` branches inside a role query (recursive isModelQueryShape) — fromLinks', () => {
877
+ const flowUri = 'ns://BadOrRoleFlow';
878
+ const stateUri = 'ns://BadOrRoleFlow.gate';
879
+ const badLinks: Link[] = [
880
+ { source: flowUri, predicate: 'rdf://type', target: 'ad4m://Flow' },
881
+ { source: flowUri, predicate: 'ad4m://flowName', target: Literal.from('BadOrRoleFlow').toUrl() },
882
+ { source: flowUri, predicate: 'ad4m://hasState', target: stateUri },
883
+ { source: stateUri, predicate: 'rdf://type', target: 'ad4m://FlowState' },
884
+ { source: stateUri, predicate: 'ad4m://stateName', target: Literal.from('gate').toUrl() },
885
+ { source: stateUri, predicate: 'ad4m://stateValue', target: Literal.from(0).toUrl() },
886
+ {
887
+ source: stateUri,
888
+ predicate: 'ad4m://stateCheck',
889
+ target: `literal:string:${encodeURIComponent(JSON.stringify({ predicate: 'p', target: 't' }))}`,
890
+ },
891
+ {
892
+ source: stateUri,
893
+ predicate: 'ad4m://consensusRule',
894
+ target: `literal:string:${encodeURIComponent(
895
+ JSON.stringify({
896
+ n: 1,
897
+ fromRole: {
898
+ className: 'ns://Composed',
899
+ or: [{ className: 'ns://Ok' }, null, { didProperty: 'agent' }],
900
+ },
901
+ }),
902
+ )}`,
903
+ },
904
+ ];
905
+
906
+ const flow = SHACLFlow.fromLinks(badLinks, flowUri);
907
+ expect(flow.states[0].consensusRule).toBeUndefined();
908
+ });
909
+
910
+ it('rejects malformed `or` branches inside a role query (recursive isModelQueryShape) — fromJSON', () => {
911
+ const flow = SHACLFlow.fromJSON({
912
+ name: 'BadOrRole',
913
+ namespace: 'ns://',
914
+ states: [
915
+ {
916
+ name: 'Gate',
917
+ value: 0,
918
+ consensusRule: {
919
+ n: 1,
920
+ fromRole: {
921
+ className: 'ns://Composed',
922
+ or: [{ className: 'ns://Ok' }, null, { didProperty: 'agent' }],
923
+ },
924
+ },
925
+ },
926
+ ],
927
+ transitions: [],
928
+ } as any);
929
+ expect(flow.states[0].consensusRule).toBeUndefined();
930
+ });
931
+
932
+ it('rejects a `requires` ModelQuery whose nested `or` branch is malformed', () => {
933
+ const flow = SHACLFlow.fromJSON({
934
+ name: 'BadRequiresOr',
935
+ namespace: 'ns://',
936
+ states: [
937
+ {
938
+ name: 'Gate',
939
+ value: 0,
940
+ requires: [{ className: 'ns://Root', or: [{ className: 'ns://Ok' }, null] }],
941
+ },
942
+ ],
943
+ transitions: [],
944
+ } as any);
945
+ expect(flow.states[0].requires).toBeUndefined();
946
+ });
947
+
948
+ it('accepts a role query in `$did`-templated Shape 2 form (no didProperty)', () => {
949
+ const flow = new SHACLFlow('Gated', 'ns://');
950
+ const rule: ConsensusRule = {
951
+ n: 1,
952
+ fromRole: {
953
+ className: 'ns://Reputation',
954
+ where: { agent: '$did', score: { equals: 100 } as any },
955
+ },
956
+ };
957
+ flow.consensusRule = rule;
958
+
959
+ const roundTripped = SHACLFlow.fromLinks(flow.toLinks(), flow.flowUri);
960
+ expect(roundTripped.consensusRule?.fromRole?.didProperty).toBeUndefined();
961
+ expect(roundTripped.consensusRule?.fromRole?.where?.agent).toBe('$did');
962
+ });
963
+ });
237
964
  });