@coasys/ad4m 0.13.0-test-interpretation-1 → 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 (279) hide show
  1. package/lib/index.cjs +2409 -625
  2. package/lib/index.js +2406 -626
  3. package/lib/src/Literal.js +8 -0
  4. package/lib/src/ai/AIClient.js +6 -3
  5. package/lib/src/apiClient.d.ts +40 -4
  6. package/lib/src/apiClient.js +149 -9
  7. package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
  8. package/lib/src/index.d.ts +3 -1
  9. package/lib/src/index.js +2 -0
  10. package/lib/src/model/Ad4mModel.d.ts +34 -16
  11. package/lib/src/model/Ad4mModel.js +302 -63
  12. package/lib/src/model/Ad4mModel.test.js +480 -735
  13. package/lib/src/model/ModelQueryBuilder.js +2 -2
  14. package/lib/src/model/decorators.d.ts +199 -12
  15. package/lib/src/model/decorators.js +88 -32
  16. package/lib/src/model/json-schema.js +7 -21
  17. package/lib/src/model/model-manifest.d.ts +41 -0
  18. package/lib/src/model/model-manifest.js +11 -0
  19. package/lib/src/model/query-common.d.ts +2 -2
  20. package/lib/src/model/query-sparql.d.ts +62 -0
  21. package/lib/src/model/query-sparql.js +78 -15
  22. package/lib/src/model/query-sparql.test.js +92 -10
  23. package/lib/src/model/query-utils.d.ts +7 -2
  24. package/lib/src/model/query-utils.js +21 -11
  25. package/lib/src/model/shacl-gen.js +77 -15
  26. package/lib/src/model/types.d.ts +32 -8
  27. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +33 -33
  28. package/lib/src/perspectives/AutoProcessor.d.ts +198 -2
  29. package/lib/src/perspectives/FlowInstance.d.ts +187 -0
  30. package/lib/src/perspectives/FlowInstance.js +336 -0
  31. package/lib/src/perspectives/FlowModels.d.ts +94 -0
  32. package/lib/src/perspectives/FlowModels.js +182 -0
  33. package/lib/src/perspectives/InterpretationModels.d.ts +41 -3
  34. package/lib/src/perspectives/InterpretationModels.js +60 -26
  35. package/lib/src/perspectives/PerspectiveClient.d.ts +88 -7
  36. package/lib/src/perspectives/PerspectiveClient.js +138 -11
  37. package/lib/src/perspectives/PerspectiveProxy.d.ts +150 -57
  38. package/lib/src/perspectives/PerspectiveProxy.js +411 -287
  39. package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
  40. package/lib/src/perspectives/SparqlBindings.js +57 -6
  41. package/lib/src/shacl/SHACLFlow.d.ts +273 -47
  42. package/lib/src/shacl/SHACLFlow.js +397 -88
  43. package/lib/src/shacl/SHACLShape.d.ts +19 -3
  44. package/lib/src/shacl/SHACLShape.js +30 -1
  45. package/lib/src/shacl/SHACLShape.test.js +82 -0
  46. package/lib/src/shacl/index.d.ts +1 -1
  47. package/lib/src/shacl/index.js +1 -1
  48. package/package.json +3 -3
  49. package/src/Literal.ts +7 -0
  50. package/src/ai/AIClient.ts +6 -3
  51. package/src/apiClient.test.ts +227 -0
  52. package/src/apiClient.ts +185 -9
  53. package/src/generated/api/RunInterpretationRequest.ts +19 -3
  54. package/src/index.ts +3 -1
  55. package/src/model/Ad4mModel.test.ts +729 -22
  56. package/src/model/Ad4mModel.ts +305 -66
  57. package/src/model/ModelQueryBuilder.ts +2 -2
  58. package/src/model/decorators.ts +278 -44
  59. package/src/model/json-schema.ts +10 -25
  60. package/src/model/query-common.ts +2 -2
  61. package/src/model/query-sparql.test.ts +114 -13
  62. package/src/model/query-sparql.ts +83 -14
  63. package/src/model/query-utils.ts +22 -12
  64. package/src/model/relation-filtering.test.ts +70 -20
  65. package/src/model/shacl-gen.ts +78 -13
  66. package/src/model/shacl-roundtrip.test.ts +134 -2
  67. package/src/model/types.ts +30 -8
  68. package/src/perspectives/AutoProcessor.ts +204 -2
  69. package/src/perspectives/FlowInstance.ts +369 -0
  70. package/src/perspectives/FlowModels.ts +157 -0
  71. package/src/perspectives/InterpretationModels.ts +91 -21
  72. package/src/perspectives/PerspectiveClient.test.ts +67 -6
  73. package/src/perspectives/PerspectiveClient.ts +190 -14
  74. package/src/perspectives/PerspectiveProxy.test.ts +406 -0
  75. package/src/perspectives/PerspectiveProxy.ts +494 -308
  76. package/src/perspectives/SparqlBindings.test.ts +134 -0
  77. package/src/perspectives/SparqlBindings.ts +57 -6
  78. package/src/perspectives/shacl-rpc.test.ts +258 -0
  79. package/src/shacl/SHACLFlow.test.ts +762 -35
  80. package/src/shacl/SHACLFlow.ts +680 -112
  81. package/src/shacl/SHACLShape.test.ts +30 -4
  82. package/src/shacl/SHACLShape.ts +59 -6
  83. package/src/shacl/index.ts +1 -1
  84. package/lib/src/generated/rest/AIModelLoadingStatus.d.ts +0 -7
  85. package/lib/src/generated/rest/AIModelLoadingStatus.js +0 -2
  86. package/lib/src/generated/rest/AddAgentInfosRequest.d.ts +0 -3
  87. package/lib/src/generated/rest/AddAgentInfosRequest.js +0 -2
  88. package/lib/src/generated/rest/AddLinkExpressionRequest.d.ts +0 -6
  89. package/lib/src/generated/rest/AddLinkExpressionRequest.js +0 -1
  90. package/lib/src/generated/rest/AddLinkRequest.d.ts +0 -6
  91. package/lib/src/generated/rest/AddLinkRequest.js +0 -1
  92. package/lib/src/generated/rest/AddLinksBulkRequest.d.ts +0 -6
  93. package/lib/src/generated/rest/AddLinksBulkRequest.js +0 -1
  94. package/lib/src/generated/rest/AddSdnaRequest.d.ts +0 -6
  95. package/lib/src/generated/rest/AddSdnaRequest.js +0 -2
  96. package/lib/src/generated/rest/ApplyTemplateRequest.d.ts +0 -4
  97. package/lib/src/generated/rest/ApplyTemplateRequest.js +0 -2
  98. package/lib/src/generated/rest/AuthInfoInput.d.ts +0 -10
  99. package/lib/src/generated/rest/AuthInfoInput.js +0 -1
  100. package/lib/src/generated/rest/BroadcastRequest.d.ts +0 -6
  101. package/lib/src/generated/rest/BroadcastRequest.js +0 -1
  102. package/lib/src/generated/rest/CapabilityInput.d.ts +0 -5
  103. package/lib/src/generated/rest/CapabilityInput.js +0 -1
  104. package/lib/src/generated/rest/CommitBatchRequest.d.ts +0 -3
  105. package/lib/src/generated/rest/CommitBatchRequest.js +0 -2
  106. package/lib/src/generated/rest/ComputeLogEntry.d.ts +0 -9
  107. package/lib/src/generated/rest/ComputeLogEntry.js +0 -2
  108. package/lib/src/generated/rest/CreateExpressionRequest.d.ts +0 -4
  109. package/lib/src/generated/rest/CreateExpressionRequest.js +0 -2
  110. package/lib/src/generated/rest/CreatePerspectiveRequest.d.ts +0 -3
  111. package/lib/src/generated/rest/CreatePerspectiveRequest.js +0 -2
  112. package/lib/src/generated/rest/CreateSubjectRequest.d.ts +0 -6
  113. package/lib/src/generated/rest/CreateSubjectRequest.js +0 -2
  114. package/lib/src/generated/rest/CreateUserRequest.d.ts +0 -4
  115. package/lib/src/generated/rest/CreateUserRequest.js +0 -2
  116. package/lib/src/generated/rest/CreateUserResponse.d.ts +0 -5
  117. package/lib/src/generated/rest/CreateUserResponse.js +0 -2
  118. package/lib/src/generated/rest/DecoratedExpressionProof.d.ts +0 -6
  119. package/lib/src/generated/rest/DecoratedExpressionProof.js +0 -2
  120. package/lib/src/generated/rest/DecoratedLinkExpression.d.ts +0 -10
  121. package/lib/src/generated/rest/DecoratedLinkExpression.js +0 -1
  122. package/lib/src/generated/rest/DisposeQueryRequest.d.ts +0 -3
  123. package/lib/src/generated/rest/DisposeQueryRequest.js +0 -2
  124. package/lib/src/generated/rest/EmailTestRequest.d.ts +0 -6
  125. package/lib/src/generated/rest/EmailTestRequest.js +0 -2
  126. package/lib/src/generated/rest/EmbedRequest.d.ts +0 -4
  127. package/lib/src/generated/rest/EmbedRequest.js +0 -2
  128. package/lib/src/generated/rest/EntanglementProofInput.d.ts +0 -6
  129. package/lib/src/generated/rest/EntanglementProofInput.js +0 -2
  130. package/lib/src/generated/rest/EntanglementProofPreflightRequest.d.ts +0 -4
  131. package/lib/src/generated/rest/EntanglementProofPreflightRequest.js +0 -2
  132. package/lib/src/generated/rest/ExecuteCommandsRequest.d.ts +0 -4
  133. package/lib/src/generated/rest/ExecuteCommandsRequest.js +0 -2
  134. package/lib/src/generated/rest/ExportRequest.d.ts +0 -5
  135. package/lib/src/generated/rest/ExportRequest.js +0 -2
  136. package/lib/src/generated/rest/ExpressionManyRequest.d.ts +0 -3
  137. package/lib/src/generated/rest/ExpressionManyRequest.js +0 -2
  138. package/lib/src/generated/rest/ExpressionProof.d.ts +0 -4
  139. package/lib/src/generated/rest/ExpressionProof.js +0 -2
  140. package/lib/src/generated/rest/ExpressionProofInput.d.ts +0 -6
  141. package/lib/src/generated/rest/ExpressionProofInput.js +0 -2
  142. package/lib/src/generated/rest/FriendSendMessageRequest.d.ts +0 -3
  143. package/lib/src/generated/rest/FriendSendMessageRequest.js +0 -2
  144. package/lib/src/generated/rest/FriendsListRequest.d.ts +0 -3
  145. package/lib/src/generated/rest/FriendsListRequest.js +0 -2
  146. package/lib/src/generated/rest/GenerateAgentRequest.d.ts +0 -3
  147. package/lib/src/generated/rest/GenerateAgentRequest.js +0 -2
  148. package/lib/src/generated/rest/GenerateJwtRequest.d.ts +0 -4
  149. package/lib/src/generated/rest/GenerateJwtRequest.js +0 -2
  150. package/lib/src/generated/rest/GetSubjectDataRequest.d.ts +0 -4
  151. package/lib/src/generated/rest/GetSubjectDataRequest.js +0 -2
  152. package/lib/src/generated/rest/HostingInfoResponse.d.ts +0 -5
  153. package/lib/src/generated/rest/HostingInfoResponse.js +0 -2
  154. package/lib/src/generated/rest/HostingWalletResponse.d.ts +0 -4
  155. package/lib/src/generated/rest/HostingWalletResponse.js +0 -2
  156. package/lib/src/generated/rest/ImportAgentRequest.d.ts +0 -6
  157. package/lib/src/generated/rest/ImportAgentRequest.js +0 -2
  158. package/lib/src/generated/rest/ImportRequest.d.ts +0 -4
  159. package/lib/src/generated/rest/ImportRequest.js +0 -2
  160. package/lib/src/generated/rest/JoinNeighbourhoodRequest.d.ts +0 -3
  161. package/lib/src/generated/rest/JoinNeighbourhoodRequest.js +0 -2
  162. package/lib/src/generated/rest/KeepAliveQueryRequest.d.ts +0 -3
  163. package/lib/src/generated/rest/KeepAliveQueryRequest.js +0 -2
  164. package/lib/src/generated/rest/LanguageMetaInput.d.ts +0 -6
  165. package/lib/src/generated/rest/LanguageMetaInput.js +0 -2
  166. package/lib/src/generated/rest/Link.d.ts +0 -5
  167. package/lib/src/generated/rest/Link.js +0 -2
  168. package/lib/src/generated/rest/LinkExpression.d.ts +0 -10
  169. package/lib/src/generated/rest/LinkExpression.js +0 -1
  170. package/lib/src/generated/rest/LinkExpressionInput.d.ts +0 -10
  171. package/lib/src/generated/rest/LinkExpressionInput.js +0 -1
  172. package/lib/src/generated/rest/LinkInput.d.ts +0 -5
  173. package/lib/src/generated/rest/LinkInput.js +0 -2
  174. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.d.ts +0 -3
  175. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.js +0 -2
  176. package/lib/src/generated/rest/LinkMutationRequest.d.ts +0 -12
  177. package/lib/src/generated/rest/LinkMutationRequest.js +0 -1
  178. package/lib/src/generated/rest/LinkMutationResponse.d.ts +0 -9
  179. package/lib/src/generated/rest/LinkMutationResponse.js +0 -1
  180. package/lib/src/generated/rest/LinkMutations.d.ts +0 -6
  181. package/lib/src/generated/rest/LinkMutations.js +0 -1
  182. package/lib/src/generated/rest/LinkMutationsRequest.d.ts +0 -5
  183. package/lib/src/generated/rest/LinkMutationsRequest.js +0 -1
  184. package/lib/src/generated/rest/LinkStatus.d.ts +0 -1
  185. package/lib/src/generated/rest/LinkStatus.js +0 -2
  186. package/lib/src/generated/rest/LinkUpdateInput.d.ts +0 -5
  187. package/lib/src/generated/rest/LinkUpdateInput.js +0 -1
  188. package/lib/src/generated/rest/LockAgentRequest.d.ts +0 -3
  189. package/lib/src/generated/rest/LockAgentRequest.js +0 -2
  190. package/lib/src/generated/rest/LoginUserRequest.d.ts +0 -5
  191. package/lib/src/generated/rest/LoginUserRequest.js +0 -2
  192. package/lib/src/generated/rest/ModelType.d.ts +0 -1
  193. package/lib/src/generated/rest/ModelType.js +0 -2
  194. package/lib/src/generated/rest/NotificationGrantRequest.d.ts +0 -3
  195. package/lib/src/generated/rest/NotificationGrantRequest.js +0 -2
  196. package/lib/src/generated/rest/NotificationInput.d.ts +0 -10
  197. package/lib/src/generated/rest/NotificationInput.js +0 -2
  198. package/lib/src/generated/rest/OpenLinkRequest.d.ts +0 -3
  199. package/lib/src/generated/rest/OpenLinkRequest.js +0 -2
  200. package/lib/src/generated/rest/PermitCapabilityRequest.d.ts +0 -3
  201. package/lib/src/generated/rest/PermitCapabilityRequest.js +0 -2
  202. package/lib/src/generated/rest/PerspectiveInput.d.ts +0 -4
  203. package/lib/src/generated/rest/PerspectiveInput.js +0 -1
  204. package/lib/src/generated/rest/PromptRequest.d.ts +0 -4
  205. package/lib/src/generated/rest/PromptRequest.js +0 -2
  206. package/lib/src/generated/rest/PublicPerspectiveInput.d.ts +0 -4
  207. package/lib/src/generated/rest/PublicPerspectiveInput.js +0 -1
  208. package/lib/src/generated/rest/PublishLanguageRequest.d.ts +0 -5
  209. package/lib/src/generated/rest/PublishLanguageRequest.js +0 -1
  210. package/lib/src/generated/rest/PublishNeighbourhoodRequest.d.ts +0 -6
  211. package/lib/src/generated/rest/PublishNeighbourhoodRequest.js +0 -1
  212. package/lib/src/generated/rest/QueryRequest.d.ts +0 -7
  213. package/lib/src/generated/rest/QueryRequest.js +0 -2
  214. package/lib/src/generated/rest/RemoveLinkRequest.d.ts +0 -5
  215. package/lib/src/generated/rest/RemoveLinkRequest.js +0 -1
  216. package/lib/src/generated/rest/RemoveLinksBulkRequest.d.ts +0 -5
  217. package/lib/src/generated/rest/RemoveLinksBulkRequest.js +0 -1
  218. package/lib/src/generated/rest/RequestCapabilityRequest.d.ts +0 -4
  219. package/lib/src/generated/rest/RequestCapabilityRequest.js +0 -1
  220. package/lib/src/generated/rest/RequestPaymentRequest.d.ts +0 -3
  221. package/lib/src/generated/rest/RequestPaymentRequest.js +0 -2
  222. package/lib/src/generated/rest/RequestVerificationRequest.d.ts +0 -4
  223. package/lib/src/generated/rest/RequestVerificationRequest.js +0 -2
  224. package/lib/src/generated/rest/ResourceInput.d.ts +0 -4
  225. package/lib/src/generated/rest/ResourceInput.js +0 -2
  226. package/lib/src/generated/rest/SetDefaultModelRequest.d.ts +0 -4
  227. package/lib/src/generated/rest/SetDefaultModelRequest.js +0 -1
  228. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.d.ts +0 -3
  229. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.js +0 -2
  230. package/lib/src/generated/rest/SetHotWalletAddressRequest.d.ts +0 -3
  231. package/lib/src/generated/rest/SetHotWalletAddressRequest.js +0 -2
  232. package/lib/src/generated/rest/SetMultiUserRequest.d.ts +0 -3
  233. package/lib/src/generated/rest/SetMultiUserRequest.js +0 -2
  234. package/lib/src/generated/rest/SetOnlineStatusRequest.d.ts +0 -5
  235. package/lib/src/generated/rest/SetOnlineStatusRequest.js +0 -1
  236. package/lib/src/generated/rest/SetStatusRequest.d.ts +0 -3
  237. package/lib/src/generated/rest/SetStatusRequest.js +0 -2
  238. package/lib/src/generated/rest/SetUserFreeAccessRequest.d.ts +0 -4
  239. package/lib/src/generated/rest/SetUserFreeAccessRequest.js +0 -2
  240. package/lib/src/generated/rest/SignMessageRequest.d.ts +0 -3
  241. package/lib/src/generated/rest/SignMessageRequest.js +0 -2
  242. package/lib/src/generated/rest/SignalRequest.d.ts +0 -6
  243. package/lib/src/generated/rest/SignalRequest.js +0 -1
  244. package/lib/src/generated/rest/SubscribeQueryRequest.d.ts +0 -3
  245. package/lib/src/generated/rest/SubscribeQueryRequest.js +0 -2
  246. package/lib/src/generated/rest/SubscribeQueryResponse.d.ts +0 -4
  247. package/lib/src/generated/rest/SubscribeQueryResponse.js +0 -2
  248. package/lib/src/generated/rest/TrustedAgentsRequest.d.ts +0 -3
  249. package/lib/src/generated/rest/TrustedAgentsRequest.js +0 -2
  250. package/lib/src/generated/rest/UnlockAgentRequest.d.ts +0 -4
  251. package/lib/src/generated/rest/UnlockAgentRequest.js +0 -2
  252. package/lib/src/generated/rest/UpdateLinkRequest.d.ts +0 -7
  253. package/lib/src/generated/rest/UpdateLinkRequest.js +0 -1
  254. package/lib/src/generated/rest/UpdatePerspectiveRequest.d.ts +0 -3
  255. package/lib/src/generated/rest/UpdatePerspectiveRequest.js +0 -2
  256. package/lib/src/generated/rest/UpdateProfileRequest.d.ts +0 -5
  257. package/lib/src/generated/rest/UpdateProfileRequest.js +0 -1
  258. package/lib/src/generated/rest/UserStatistics.d.ts +0 -9
  259. package/lib/src/generated/rest/UserStatistics.js +0 -2
  260. package/lib/src/generated/rest/VerificationRequestResult.d.ts +0 -6
  261. package/lib/src/generated/rest/VerificationRequestResult.js +0 -2
  262. package/lib/src/generated/rest/VerifyEmailRequest.d.ts +0 -6
  263. package/lib/src/generated/rest/VerifyEmailRequest.js +0 -2
  264. package/lib/src/generated/rest/VerifySignatureRequest.d.ts +0 -5
  265. package/lib/src/generated/rest/VerifySignatureRequest.js +0 -2
  266. package/lib/src/generated/rest/WriteSettingsRequest.d.ts +0 -3
  267. package/lib/src/generated/rest/WriteSettingsRequest.js +0 -2
  268. package/lib/src/generated/rest/index.d.ts +0 -73
  269. package/lib/src/generated/rest/index.js +0 -8
  270. package/lib/src/generated/rest/routes.d.ts +0 -587
  271. package/lib/src/generated/rest/routes.js +0 -3
  272. package/lib/src/model/query-surreal.d.ts +0 -44
  273. package/lib/src/model/query-surreal.js +0 -249
  274. package/lib/src/model/surreal-utils.d.ts +0 -42
  275. package/lib/src/model/surreal-utils.js +0 -128
  276. package/lib/src/perspectives/PerspectiveProxy.test.d.ts +0 -1
  277. package/lib/src/perspectives/PerspectiveProxy.test.js +0 -34
  278. package/lib/src/restClient.d.ts +0 -52
  279. package/lib/src/restClient.js +0 -227
@@ -1,21 +1,18 @@
1
1
  import { NeighbourhoodClient } from "./NeighbourhoodClient";
2
2
  import { NeighbourhoodProxy } from "./NeighbourhoodProxy";
3
- // Mock RestClient's subscribe to avoid real WebSocket connections
4
- jest.mock('../restClient', () => {
5
- return {
6
- RestClient: jest.fn().mockImplementation(() => ({
7
- get: jest.fn(),
8
- post: jest.fn(),
9
- put: jest.fn(),
10
- delete: jest.fn(),
11
- subscribe: jest.fn().mockReturnValue(() => { }),
12
- }))
13
- };
14
- });
15
3
  describe("NeighbourhoodProxy", () => {
16
4
  it("should add multiple signal handlers", async () => {
17
5
  const neighbourhoodURI = "did://123";
18
- const neighbourhoodClient = new NeighbourhoodClient("http://localhost:0", "test-token");
6
+ const mockApolloClient = {
7
+ subscribe: () => ({
8
+ subscribe: () => new Promise((resolve) => {
9
+ setTimeout(() => {
10
+ resolve({});
11
+ }, 10);
12
+ }),
13
+ }),
14
+ };
15
+ const neighbourhoodClient = new NeighbourhoodClient(mockApolloClient);
19
16
  const neighbourhoodProxy = new NeighbourhoodProxy(neighbourhoodClient, neighbourhoodURI);
20
17
  let callbacks = 0;
21
18
  const handler1 = () => {
@@ -24,7 +21,7 @@ describe("NeighbourhoodProxy", () => {
24
21
  const handler2 = () => {
25
22
  callbacks++;
26
23
  };
27
- // Add multiple signal handlers in parallel
24
+ // Add multiple signal handlers in paralell
28
25
  const promise = neighbourhoodProxy.addSignalHandler(handler1);
29
26
  neighbourhoodProxy.addSignalHandler(handler2);
30
27
  await promise;
@@ -33,20 +30,21 @@ describe("NeighbourhoodProxy", () => {
33
30
  });
34
31
  it("should not add multiple subscriptions when removing and adding another signal handler", async () => {
35
32
  const neighbourhoodURI = "did://123";
36
- // Track subscribe calls via the mock
37
- let subscribeCallCount = 0;
38
- const { RestClient } = jest.requireMock('../restClient');
39
- RestClient.mockImplementation(() => ({
40
- get: jest.fn(),
41
- post: jest.fn(),
42
- put: jest.fn(),
43
- delete: jest.fn(),
44
- subscribe: jest.fn().mockImplementation(() => {
45
- subscribeCallCount++;
46
- return () => { };
33
+ const subscriptions = [];
34
+ const subscribe = (args) => {
35
+ subscriptions.push(args);
36
+ new Promise((resolve) => {
37
+ setTimeout(() => {
38
+ resolve({});
39
+ }, 10);
40
+ });
41
+ };
42
+ const mockApolloClient = {
43
+ subscribe: () => ({
44
+ subscribe,
47
45
  }),
48
- }));
49
- const neighbourhoodClient = new NeighbourhoodClient("http://localhost:0", "test-token");
46
+ };
47
+ const neighbourhoodClient = new NeighbourhoodClient(mockApolloClient);
50
48
  const neighbourhoodProxy = new NeighbourhoodProxy(neighbourhoodClient, neighbourhoodURI);
51
49
  let callbacks1 = 0;
52
50
  let callbacks2 = 0;
@@ -58,15 +56,17 @@ describe("NeighbourhoodProxy", () => {
58
56
  };
59
57
  // Add signal handler 1
60
58
  await neighbourhoodProxy.addSignalHandler(handler1);
61
- // Remove signal handler 1
59
+ // Remove signal handler 2
62
60
  neighbourhoodProxy.removeSignalHandler(handler1);
63
61
  // Add signal handler 2
64
62
  await neighbourhoodProxy.addSignalHandler(handler2);
65
- // Check that only one subscription was added (handlers share subscription per perspective)
66
- expect(subscribeCallCount).toBe(1);
67
- // Dispatch signal
68
- neighbourhoodClient.dispatchSignal(neighbourhoodURI, true);
69
- // Check that only handler2 was called (handler1 was removed)
63
+ // Check that only one subscription was added
64
+ expect(subscriptions.length).toBe(1);
65
+ // mock trigger signal event
66
+ for (const subscription of subscriptions) {
67
+ subscription.next({ data: { signal: { neighbourhoodSignal: true } } });
68
+ }
69
+ // Check that only our second callback was called
70
70
  expect(callbacks1).toBe(0);
71
71
  expect(callbacks2).toBe(1);
72
72
  });
@@ -1,5 +1,76 @@
1
- /** One step in an auto-processor pass (serde camelCase of the Rust enum). */
2
- export type AutoProcessorStep = "batchReady" | "claimed" | "backedOff" | "awaitingAuthor" | "notCandidate" | "gatheringTranscript" | "runningInterpretation" | "processed" | "shapesMissing" | "emptyTranscript";
1
+ /**
2
+ * Raw form of `Scope` (parent node + linking predicate) — the only variant
3
+ * the WebSocket auto-processor config accepts. `Scope`'s model form
4
+ * (`{ model: typeof Ad4mModel, id, field? }`) references a JS class
5
+ * constructor, which JSON.stringify silently drops, so the executor would
6
+ * receive `{ id }` and the scope would be unresolvable. Client callers who
7
+ * hold a model class should resolve its predicate via
8
+ * `ModelQueryBuilder.buildParentScope()` first and pass the result here.
9
+ */
10
+ export type RawScope = {
11
+ id: string;
12
+ predicate: string;
13
+ };
14
+ /**
15
+ * One step in an auto-processor pass (serde camelCase of the Rust enum).
16
+ *
17
+ * ## Lifecycle (winning peer, emitDebugEvents: true)
18
+ *
19
+ * A pass on the winning executor emits, in order:
20
+ *
21
+ * 1. `batchReady` — debounced batch reached threshold, pass starting
22
+ * 2. `claimed` — this executor won the `try_claim`
23
+ * 3. `gatheringTranscript` — pulling the batch's transcript turns
24
+ * 4. `runningInterpretation` — about to invoke the LLM
25
+ * 5. `llmRequestSent` — prompt built + dispatched; carries `llmInput`
26
+ * (only when `emitDebugEvents: true`)
27
+ * 6. `llmResponseReceived` — LLM response arrived; carries `llmOutput`
28
+ * (only when `emitDebugEvents: true`) — the UI
29
+ * can render "waiting on LLM" between steps 5-6
30
+ * 7. `processed` — pass complete; carries `bases[]` (new/updated
31
+ * instance URIs)
32
+ *
33
+ * ## Lifecycle (losing peer, or short-circuit)
34
+ *
35
+ * - `batchReady` → `backedOff` — another peer claimed the batch first
36
+ * - `batchReady` → `awaitingAuthor` — no author of the batch is online
37
+ * - `batchReady` → `notCandidate` — this peer stood down for an earlier author
38
+ * - `claimed` → `shapesMissing` — a configured class shape hasn't synced
39
+ * - `claimed` → `emptyTranscript` — the batch drained empty
40
+ * - any → `failed` — the model errored or timed out;
41
+ * `detail` carries why. Distinct from the two above, which are the pass
42
+ * correctly finding nothing to do — reporting "nothing to extract" when
43
+ * the LLM endpoint was unreachable points someone at their transcript
44
+ * instead of at their model settings.
45
+ *
46
+ * ## Lifecycle (one-shot `runInterpretation`)
47
+ *
48
+ * A one-shot pass emits nothing unless the caller passes `observe` (see
49
+ * {@link PerspectiveProxy.runInterpretation}). With it:
50
+ *
51
+ * `runningInterpretation` → [`llmRequestSent` → `llmResponseReceived`] →
52
+ * `processed` | `failed`
53
+ *
54
+ * — plus `claimed` → `finished`/`abandoned` on the neighbourhood stream, so
55
+ * one-shot and watch passes render through the same consumer code. There is
56
+ * no `batchReady`, `gatheringTranscript` or claim: the caller supplied the
57
+ * transcript, and `processorId`/`batchKey` both carry the caller's own
58
+ * `observationId`.
59
+ *
60
+ * ## Payload fields per step
61
+ *
62
+ * All steps carry `perspectiveUuid`, `processorId`, `agentDid`, `itemIds[]`
63
+ * and `batchKey` (the join key to the neighbourhood-state stream).
64
+ * Additional payload:
65
+ *
66
+ * - `backedOff`, `notCandidate` → `detail` = holder / elected-author DID
67
+ * - `shapesMissing` → `detail` = comma-joined missing class URIs
68
+ * - `failed` → `detail` = the error
69
+ * - `llmRequestSent` → `llmInput` = raw prompt
70
+ * - `llmResponseReceived` → `llmOutput` = raw LLM response
71
+ * - `processed` → `bases[]` = new/updated instance URIs
72
+ */
73
+ export type AutoProcessorStep = "batchReady" | "claimed" | "backedOff" | "awaitingAuthor" | "notCandidate" | "gatheringTranscript" | "runningInterpretation" | "llmRequestSent" | "llmResponseReceived" | "toolCall" | "toolResult" | "processed" | "shapesMissing" | "emptyTranscript" | "failed";
3
74
  /** A single step-signal from one auto-processor pass on one perspective. */
4
75
  export interface AutoProcessorEvent {
5
76
  type: "auto-processor-event";
@@ -10,10 +81,111 @@ export interface AutoProcessorEvent {
10
81
  step: AutoProcessorStep;
11
82
  /** The batch's source item ids (present from `batchReady` onward). */
12
83
  itemIds: string[];
84
+ /**
85
+ * Content hash of the batch — the same value
86
+ * {@link AutoProcessorNeighbourhoodStateEvent.batchKey} carries, and the
87
+ * key that joins the two streams.
88
+ *
89
+ * A UI that renders one row per pass subscribes to both: the
90
+ * perspective-scoped neighbourhood stream opens the row (and names the
91
+ * claimant), while this DID-scoped stream fills in the fine-grained
92
+ * steps and LLM I/O for the pass this agent is running. Matching them on
93
+ * `processorId` alone breaks as soon as a processor runs a second pass;
94
+ * matching on `itemIds` means re-implementing the Rust SHA-256 and its
95
+ * exact serialization. So both streams carry the same key.
96
+ *
97
+ * Present from `batchReady` onward. Optional on the type because a
98
+ * pre-#903 executor does not send it — treat its absence as "cannot
99
+ * correlate", not as an error.
100
+ */
101
+ batchKey?: string;
13
102
  /** Instance base URIs written by the pass (present on `processed`). */
14
103
  bases: string[];
15
104
  /** Free-form context for the step (a holder/elected DID, an error, …). */
16
105
  detail?: string;
106
+ /** Raw LLM prompt this pass fed the model. Present ONLY on
107
+ * `llmRequestSent` events, and only when the processor was configured
108
+ * with `emitDebugEvents: true`. Never carried on `processed`. */
109
+ llmInput?: string;
110
+ /** Raw LLM response this pass received. Present ONLY on
111
+ * `llmResponseReceived` events, and only when the processor was
112
+ * configured with `emitDebugEvents: true`. Never carried on `processed`. */
113
+ llmOutput?: string;
114
+ /**
115
+ * Name of the tool the harness LLM invoked (or that just returned).
116
+ * Present on `toolCall` + `toolResult` events (harness path only).
117
+ */
118
+ toolName?: string;
119
+ /**
120
+ * JSON-encoded arguments the LLM sent to the tool. Present ONLY on
121
+ * `toolCall`; absent on `toolResult` where {@link toolResult} carries
122
+ * the return text instead.
123
+ */
124
+ toolArgsJson?: string;
125
+ /**
126
+ * The tool's return text. Present ONLY on `toolResult`; may be
127
+ * pre-truncated by the emitter with an `…[truncated for event]`
128
+ * marker when the tool returns a large payload (e.g. a `_query`
129
+ * result). Consumers wanting the full text can re-run the tool.
130
+ */
131
+ toolResult?: string;
132
+ }
133
+ /**
134
+ * Coarse-grained phase of a neighbourhood-state event.
135
+ *
136
+ * `claimed` — this executor just started a pass.
137
+ * `finished` — the pass completed successfully.
138
+ * `abandoned` — the pass short-circuited (missing shape / empty batch /
139
+ * error); the claim will TTL-expire.
140
+ */
141
+ export type NeighbourhoodPhase = "claimed" | "finished" | "abandoned";
142
+ /**
143
+ * `auto-processor-neighbourhood-state` — perspective-scoped observability
144
+ * event. Fires when THIS executor claims, finishes, or abandons a batch.
145
+ * Anyone with perspective read access sees it, so a UI can render "someone
146
+ * is auto-processing this" without receiving the batch payload or LLM I/O.
147
+ *
148
+ * Cross-executor visibility (peer's claim reaching us via Holochain sync) is
149
+ * NOT covered here; consumers who need that subscribe to `link-added` and
150
+ * filter for the `has_claim` predicate on the shared perspective.
151
+ */
152
+ export interface AutoProcessorNeighbourhoodStateEvent {
153
+ type: "auto-processor-neighbourhood-state";
154
+ perspectiveUuid: string;
155
+ processorId: string;
156
+ /** DID that claimed the batch — the pass owner's DID. */
157
+ claimantDid: string;
158
+ /** SHA-256 hex of the batch's item-id set — merge `claimed` + `finished`
159
+ * for the same key to render a single row in a UI. */
160
+ batchKey: string;
161
+ phase: NeighbourhoodPhase;
162
+ }
163
+ /**
164
+ * Opt a one-shot `runInterpretation` call into the same event streams a
165
+ * standing watch produces.
166
+ *
167
+ * Without it the call is silent until it resolves — which, on a local model,
168
+ * is minutes of a UI having nothing to say. With it the pass reports
169
+ * `runningInterpretation` → `processed`/`failed` on the DID-scoped stream and
170
+ * `claimed` → `finished`/`abandoned` on the perspective-scoped one.
171
+ */
172
+ export interface RunInterpretationObserveOptions {
173
+ /**
174
+ * The caller's own id for this pass, echoed back as both `processorId` and
175
+ * `batchKey` on every event it emits.
176
+ *
177
+ * Supplied by the caller rather than minted by the executor because
178
+ * `runInterpretation` is a single blocking call: there is no earlier
179
+ * response that could hand back a server-side id, so the events would
180
+ * arrive with nothing to match them against. Any value unique among this
181
+ * client's in-flight passes will do.
182
+ */
183
+ observationId: string;
184
+ /**
185
+ * Also emit `llmRequestSent` / `llmResponseReceived` with the raw prompt
186
+ * and response. Default `false`.
187
+ */
188
+ emitDebugEvents?: boolean;
17
189
  }
18
190
  /** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
19
191
  export interface AddAutoProcessorConfig {
@@ -69,6 +241,30 @@ export interface AddAutoProcessorConfig {
69
241
  * runs.
70
242
  */
71
243
  sourceWindowMs?: number;
244
+ /**
245
+ * Optional parent-scope filter for the dedup lookup: when set, only
246
+ * existing instances of the interpretation classes that live under this
247
+ * scope are candidates for upsert. Omit for the whole-perspective dedup
248
+ * set (pre-scope behaviour). Raw form only — see `RawScope`.
249
+ */
250
+ existingScope?: RawScope;
251
+ /**
252
+ * Optional parent-scope target for newly minted instances: when set,
253
+ * every base URI the pass CREATES is additionally linked as a child of
254
+ * `mintScope.id` via the scope's predicate — turning the SoA-tree
255
+ * "children live under this node" pattern from a URI-prefix convention
256
+ * into an actual graph edge. Upserts of pre-existing instances are NOT
257
+ * linked (would multi-parent unrelated graph state). Raw form only —
258
+ * see `RawScope`; the Rust watcher rejects `Model` scopes at runtime.
259
+ */
260
+ mintScope?: RawScope;
261
+ /**
262
+ * Enable full debug observability: persists the raw LLM prompt + response
263
+ * on the pass's `InterpretationRun` (`debugPrompt` / `debugResponse`) AND
264
+ * emits `LlmRequestSent` / `LlmResponseReceived` mid-pass events so a
265
+ * subscribed UI can render "waiting on LLM". Default `false`.
266
+ */
267
+ emitDebugEvents?: boolean;
72
268
  }
73
269
  /**
74
270
  * Raw REST-API response shape for a pending interpretation overlay.
@@ -0,0 +1,187 @@
1
+ /**
2
+ * `FlowInstance` — object-oriented wrapper for a running flow.
3
+ *
4
+ * Design authority: `docs/flow-interpretation-hints-design.md` §4.3.
5
+ *
6
+ * Wraps two on-graph objects:
7
+ *
8
+ * - `FlowInstanceRecord` — the raw @Model row minted by
9
+ * {@link FlowInstance.start}; carries `flow`, `subject`, `currentState`,
10
+ * and Ad4mModel's synthesised `createdAt`.
11
+ * - `SHACLFlow` — the flow definition the record is bound to. Held so
12
+ * `availableTransitions` / `currentState` object lookups don't require
13
+ * a per-call round-trip.
14
+ *
15
+ * Construct via the class factories — {@link FlowInstance.start} for the
16
+ * mint path and {@link FlowInstance.findAll} for the read path — rather
17
+ * than the `wrap` escape hatch, which exists for tests that already own
18
+ * a matched (record, shape) pair.
19
+ *
20
+ * # What's here vs. what's coming in §7 / slice 10.6
21
+ *
22
+ * Read surface (implemented today, PR #929):
23
+ * - `uri`, `subject`, `flowName`, `currentStateName`, `startedAtMillis`
24
+ * accessors.
25
+ * - `currentState` — resolves the `FlowState` on the shape whose name
26
+ * matches `record.currentState`.
27
+ * - `availableTransitions` — filters `shape.transitions` by `fromState`.
28
+ * - `proposals()` — queries `FlowTransitionProposal` records that
29
+ * target this instance's URI.
30
+ *
31
+ * Mutations + subscriptions (`proposeTransition`, `accept`, `reject`,
32
+ * `fireAction`, `onStateChange`, `onProposalAdded`, `onProposalResolved`)
33
+ * land with the consensus-engine slice (§4.3 / slice 10.6). Rather than
34
+ * ship them as `throw new Error("not yet")` stubs — which is a type-level
35
+ * lie the caller only discovers at runtime — they are simply absent from
36
+ * this class until the engine is wired.
37
+ */
38
+ import { PerspectiveProxy } from "./PerspectiveProxy";
39
+ import { FlowInstanceRecord, FlowTransitionProposal } from "./FlowModels";
40
+ import { SHACLFlow, FlowState, FlowTransition } from "../shacl/SHACLFlow";
41
+ export declare class FlowInstance {
42
+ private readonly perspective;
43
+ /** The flow definition this instance was minted against. */
44
+ readonly shape: SHACLFlow;
45
+ /**
46
+ * The on-graph record — carries `flow`, `subject`, `currentState`
47
+ * and Ad4mModel's synthesised `createdAt`. Callers can reach into it
48
+ * for anything the wrapper doesn't expose directly, but should prefer
49
+ * the wrapper accessors so future refactors of the underlying shape
50
+ * don't ripple through their code.
51
+ */
52
+ readonly record: FlowInstanceRecord;
53
+ /**
54
+ * Private constructor — construct via {@link FlowInstance.start} or
55
+ * {@link FlowInstance.findAll}. {@link FlowInstance.wrap} is the
56
+ * escape hatch for tests / direct construction cases.
57
+ */
58
+ private constructor();
59
+ /**
60
+ * Escape hatch used by {@link FlowInstance.start} and
61
+ * {@link FlowInstance.findAll} — not meant for general use, but public
62
+ * so tests that already own a `FlowInstanceRecord + SHACLFlow` pair
63
+ * (e.g. from pre-populated fixtures) can build a wrapper without
64
+ * going through the mint path.
65
+ */
66
+ static wrap(perspective: PerspectiveProxy, shape: SHACLFlow, record: FlowInstanceRecord): FlowInstance;
67
+ /**
68
+ * Mint a new `FlowInstance` on the given perspective (design doc §4.3).
69
+ *
70
+ * Idempotently registers the hardwired `FlowInstanceRecord` +
71
+ * `FlowTransitionProposal` @Model classes on first call — the on-graph
72
+ * shape matches the Rust-side hardwired SDNA (parity-locked in
73
+ * `flow-instance.test.ts` / `flow-transition-proposal.test.ts`).
74
+ *
75
+ * The returned wrapper carries the parsed `SHACLFlow` alongside the
76
+ * on-graph record, so `currentState` / `availableTransitions` /
77
+ * `proposals` accessors work without further round-trips. The consensus
78
+ * engine (slice 10.6) will read the record's `currentState` when it
79
+ * fires transitions.
80
+ *
81
+ * @param perspective - The perspective the flow instance lives on
82
+ * @param flowName - Name of a `SHACLFlow` already registered on the perspective
83
+ * @param baseExpression - URI of the subject expression the flow runs on
84
+ * @throws When the flow is unknown or has zero declared states (zero-state
85
+ * flows fire via the forthcoming atomic-action path, §6.3).
86
+ */
87
+ static start(perspective: PerspectiveProxy, flowName: string, baseExpression: string): Promise<FlowInstance>;
88
+ /**
89
+ * Return every live `FlowInstance` on the perspective (design doc §4.3).
90
+ *
91
+ * Read-only path: never registers classes. On a perspective that has
92
+ * never minted a flow instance, the `FlowInstanceRecord` SHACL shape
93
+ * isn't installed yet — this returns `[]` in that case rather than
94
+ * mutating the perspective. Registration is the responsibility of
95
+ * {@link FlowInstance.start}, which is the write path. (Registering on
96
+ * a read would sync a write to every peer in the neighbourhood —
97
+ * exactly what a query must not do — James PR #929 R7.)
98
+ *
99
+ * Filter surface (all optional, all combinable):
100
+ * - **`flowName`** — narrows by flow-name discriminator (e.g. "Delivery")
101
+ * - **`subject`** — narrows by base-expression URI, i.e. "give me every
102
+ * flow running on THIS expression"
103
+ *
104
+ * Both filters translate to a single SHACL `where`-filter round-trip
105
+ * (no client-side filtering); combining them AND-joins server-side.
106
+ * The string-arg shape (`FlowInstance.findAll(p, "Delivery")`) is
107
+ * shorthand for `{ flowName: "Delivery" }`.
108
+ *
109
+ * Records whose `flow` value has no matching `SHACLFlow` on the
110
+ * perspective (e.g. the flow was unregistered) are silently skipped —
111
+ * the wrapper can't answer `currentState` / `availableTransitions`
112
+ * without the shape, and callers routinely iterate the returned array
113
+ * without null-checks.
114
+ *
115
+ * @example
116
+ * ```typescript
117
+ * const all = await FlowInstance.findAll(perspective);
118
+ * const deliveries = await FlowInstance.findAll(perspective, "Delivery");
119
+ * const onThisTask = await FlowInstance.findAll(perspective, {
120
+ * subject: "ad4m://task/1",
121
+ * });
122
+ * const deliveriesOnTask = await FlowInstance.findAll(perspective, {
123
+ * flowName: "Delivery",
124
+ * subject: "ad4m://task/1",
125
+ * });
126
+ * ```
127
+ */
128
+ static findAll(perspective: PerspectiveProxy, filter?: string | {
129
+ flowName?: string;
130
+ subject?: string;
131
+ }): Promise<FlowInstance[]>;
132
+ /**
133
+ * URI of the on-graph `FlowInstance` node — `ad4m://flow/instance/{id}`.
134
+ *
135
+ * Sourced from `Ad4mModel`'s synthesised `baseExpression`, which for
136
+ * `FlowInstanceRecord` *is* the instance's own URI (the value
137
+ * `FlowTransitionProposal.flowInstance` references).
138
+ */
139
+ get uri(): string;
140
+ /**
141
+ * URI of the base expression this flow runs on — matches the
142
+ * `SHACLFlow.inputTypes` that {@link PerspectiveProxy.availableFlows}
143
+ * would greenlight for this expression.
144
+ */
145
+ get subject(): string;
146
+ /**
147
+ * Human-readable flow name — the display label. Sourced from the paired
148
+ * `SHACLFlow.name`, not from the record (which stores the URI as its
149
+ * canonical identity — see FlowInstanceRecord's docstring for why).
150
+ */
151
+ get flowName(): string;
152
+ /** Flow URI — the on-graph discriminator, collision-free across modules. */
153
+ get flowUri(): string;
154
+ /** Name of the state this instance is currently in. */
155
+ get currentStateName(): string;
156
+ /**
157
+ * ISO-8601 (epoch millis after Ad4mModel hydration) start time.
158
+ * Returns `undefined` when hydration didn't produce a `createdAt`
159
+ * — rare, but not fatal.
160
+ */
161
+ get startedAtMillis(): number | undefined;
162
+ /**
163
+ * The `FlowState` object on the shape matching `currentStateName`.
164
+ * Throws when the record's state name is not declared on the flow —
165
+ * that's a "stale FlowInstance whose flow was edited under it" bug,
166
+ * not a silent-fail case.
167
+ */
168
+ get currentState(): FlowState;
169
+ /**
170
+ * Every `FlowTransition` on the shape whose `fromState` matches
171
+ * `currentStateName`. Order preserved from the shape.
172
+ *
173
+ * Empty when the current state is terminal (no outgoing transitions).
174
+ */
175
+ get availableTransitions(): FlowTransition[];
176
+ /**
177
+ * All `FlowTransitionProposal` records targeting this instance's URI.
178
+ *
179
+ * Uses the SDNA identity discriminator (`ad4m://flow/instance` predicate)
180
+ * for the where-filter — one SPARQL round-trip, no client-side
181
+ * filtering.
182
+ *
183
+ * Note: the consensus engine (slice 10.6) will start writing these; today
184
+ * they only exist when a client wrote one directly (or a test seeded one).
185
+ */
186
+ proposals(): Promise<FlowTransitionProposal[]>;
187
+ }