@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
package/src/apiClient.ts CHANGED
@@ -19,6 +19,31 @@ export class RpcError extends Error {
19
19
  }
20
20
  }
21
21
 
22
+ /** Options accepted by [`ApiClient.call`]. */
23
+ export interface CallOptions {
24
+ /**
25
+ * AbortSignal that, when fired, sends a `request.cancel` to the
26
+ * executor and rejects the call with a DOMException (`name === 'AbortError'`).
27
+ *
28
+ * Use this for long-running operations like `querySparql` so a UI
29
+ * teardown or a newer query supersession can stop the in-flight one
30
+ * without paying the network + deserialise tax on its result.
31
+ *
32
+ * Cancellation is best-effort on the executor: the SPARQL evaluation
33
+ * itself isn't preempted (Oxigraph can't be interrupted), but the
34
+ * reply is discarded and the network traffic + JSON parsing on the
35
+ * client are skipped.
36
+ */
37
+ signal?: AbortSignal
38
+
39
+ /**
40
+ * Per-call timeout override in ms. Defaults to [[DEFAULT_TIMEOUT_MS]].
41
+ * Use for long-running calls (LLM prompts, holochain ops) that
42
+ * legitimately exceed the default.
43
+ */
44
+ timeoutMs?: number
45
+ }
46
+
22
47
  /** Default RPC call timeout in milliseconds (30 seconds). */
23
48
  const DEFAULT_TIMEOUT_MS = 30_000
24
49
 
@@ -69,6 +94,8 @@ export class ApiClient {
69
94
 
70
95
  private _ws: WebSocket | null = null
71
96
  private _wsCallbacks = new Set<(data: unknown) => void>()
97
+ private _reconnectCallbacks = new Set<() => void>()
98
+ private _hasConnectedOnce = false
72
99
  private _pendingCalls = new Map<string, PendingCall>()
73
100
  private _wsReady: Promise<void> | null = null
74
101
  private _wsReadyResolve: (() => void) | null = null
@@ -76,6 +103,7 @@ export class ApiClient {
76
103
  private _wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS
77
104
  private _wsClosed = false
78
105
  private _wsPingTimer: ReturnType<typeof setInterval> | null = null
106
+ private _ignoredResponseIds = new Set<string>()
79
107
 
80
108
  private _getWsUrl(): string {
81
109
  const wsBase = this.baseUrl
@@ -100,7 +128,20 @@ export class ApiClient {
100
128
  })
101
129
 
102
130
  const url = this._getWsUrl()
103
- const WsImpl = this._webSocketImpl ?? WebSocket
131
+ // Fallback order: injected impl → globalThis.WebSocket (browsers, Node ≥ 22) → require('ws') (Node ≤ 20).
132
+ // globalThis lookup avoids a ReferenceError on Node 18 where `WebSocket` is not a global.
133
+ const globalWs = (globalThis as any).WebSocket as (new (url: string) => WebSocket) | undefined
134
+ let WsImpl: new (url: string) => WebSocket
135
+ if (this._webSocketImpl) {
136
+ WsImpl = this._webSocketImpl
137
+ } else if (globalWs) {
138
+ WsImpl = globalWs
139
+ } else {
140
+ // Lazy CommonJS require so bundlers targeting browsers don't try to bundle `ws`.
141
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
142
+ const req = eval('require') as NodeRequire
143
+ WsImpl = req('ws') as new (url: string) => WebSocket
144
+ }
104
145
  const ws = new WsImpl(url)
105
146
  this._ws = ws
106
147
 
@@ -111,6 +152,16 @@ export class ApiClient {
111
152
  this._wsReadyResolve = null
112
153
  }
113
154
  this._startPing()
155
+
156
+ // Fire reconnect callbacks only on reconnect (not first connect)
157
+ if (this._hasConnectedOnce) {
158
+ for (const cb of this._reconnectCallbacks) {
159
+ try { cb() } catch (e) {
160
+ console.error('Error in reconnect callback:', e)
161
+ }
162
+ }
163
+ }
164
+ this._hasConnectedOnce = true
114
165
  }
115
166
 
116
167
  ws.onmessage = (event) => {
@@ -139,6 +190,14 @@ export class ApiClient {
139
190
  return
140
191
  }
141
192
 
193
+ // Discard ack responses to cancel requests we sent — they have
194
+ // an id that was never in _pendingCalls, so without this guard
195
+ // they'd leak into subscriber callbacks as spurious events.
196
+ if (id && this._ignoredResponseIds.has(id)) {
197
+ this._ignoredResponseIds.delete(id)
198
+ return
199
+ }
200
+
142
201
  // Server-push event (no id, or id not in pending) → route to subscribers
143
202
  for (const cb of this._wsCallbacks) cb(parsed)
144
203
  }
@@ -201,44 +260,147 @@ export class ApiClient {
201
260
  if (this._wsReady) await this._wsReady
202
261
  }
203
262
 
263
+ /**
264
+ * Like `_ready()`, but races the connection against an AbortSignal so
265
+ * that callers don't hang if the signal fires while connecting.
266
+ */
267
+ private async _readyOrAbort(signal?: AbortSignal): Promise<void> {
268
+ if (signal?.aborted) {
269
+ throw new DOMException('Aborted', 'AbortError')
270
+ }
271
+
272
+ await new Promise<void>((resolve, reject) => {
273
+ let settled = false
274
+
275
+ const finish = (fn: () => void) => {
276
+ if (settled) return
277
+ settled = true
278
+ if (signal && onAbort) {
279
+ signal.removeEventListener('abort', onAbort)
280
+ }
281
+ fn()
282
+ }
283
+
284
+ const onAbort = signal
285
+ ? () => finish(() => reject(new DOMException('Aborted', 'AbortError')))
286
+ : null
287
+
288
+ if (onAbort) {
289
+ signal!.addEventListener('abort', onAbort, { once: true })
290
+ }
291
+
292
+ this._ready().then(
293
+ () => finish(resolve),
294
+ (error) => finish(() => reject(error)),
295
+ )
296
+ })
297
+ }
298
+
204
299
  // ── RPC call method ─────────────────────────────────────────────────────
205
300
 
206
301
  /**
207
302
  * Send an RPC call over the WebSocket connection.
208
303
  * @param type - The operation type (e.g. 'agent.get', 'perspective.all')
209
304
  * @param params - Optional parameters to include in the message
210
- * @param timeoutMs - Optional per-call timeout override in ms. Defaults to
211
- * [[DEFAULT_TIMEOUT_MS]]. Use for long-running calls (LLM prompts,
212
- * holochain ops) that legitimately exceed the default.
305
+ * @param options - Optional call options: `signal` (AbortSignal for
306
+ * cancellation) and/or `timeoutMs` (per-call timeout override,
307
+ * defaults to [[DEFAULT_TIMEOUT_MS]] — use for long-running calls
308
+ * like LLM prompts or holochain ops that legitimately exceed it).
213
309
  * @returns Promise that resolves with the result from the server
214
310
  */
215
- async call<T>(type: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T> {
216
- await this._ready()
311
+ async call<T>(type: string, params?: Record<string, unknown>, options?: CallOptions): Promise<T> {
312
+ // Fast-path: if the caller already aborted, bail out before
313
+ // opening the socket. Matches fetch()'s behaviour.
314
+ const signal = options?.signal
315
+ if (signal?.aborted) {
316
+ throw new DOMException('Aborted', 'AbortError')
317
+ }
318
+
319
+ await this._readyOrAbort(signal)
217
320
 
218
321
  const id = nextId()
219
322
  // Put params under a "params" key to avoid collision with
220
323
  // protocol fields "id" and "type" (e.g. params might contain
221
324
  // { id: modelId } or { type: "db" }).
222
325
  const message: Record<string, unknown> = { id, type, params: params || {} }
223
- const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS
326
+ const effectiveTimeout = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS
224
327
 
225
328
  return new Promise<T>((resolve, reject) => {
329
+ let abortHandler: (() => void) | null = null
330
+
331
+ const cleanup = () => {
332
+ if (signal && abortHandler) {
333
+ signal.removeEventListener('abort', abortHandler)
334
+ abortHandler = null
335
+ }
336
+ }
337
+
226
338
  const timer = setTimeout(() => {
227
339
  this._pendingCalls.delete(id)
340
+ cleanup()
228
341
  reject(new RpcError(408, `RPC call '${type}' timed out after ${effectiveTimeout}ms`))
229
342
  }, effectiveTimeout)
230
343
 
344
+ // Wrap resolve/reject so we always clean up the abort listener.
231
345
  this._pendingCalls.set(id, {
232
- resolve: resolve as (value: unknown) => void,
233
- reject,
346
+ resolve: (value: unknown) => { cleanup(); resolve(value as T) },
347
+ reject: (reason: unknown) => { cleanup(); reject(reason) },
234
348
  timer,
235
349
  })
236
350
 
351
+ if (signal) {
352
+ abortHandler = () => {
353
+ // Drop the pending entry first so the late server
354
+ // reply (if any) routes to the event subscribers,
355
+ // not to a stale resolver.
356
+ this._pendingCalls.delete(id)
357
+ clearTimeout(timer)
358
+ cleanup()
359
+
360
+ // Best-effort `request.cancel` — the executor will
361
+ // race the cancellation token against the in-flight
362
+ // handler. If the socket is already gone there's
363
+ // nothing useful we can send; the client side is
364
+ // still aborted either way.
365
+ if (this._ws && this._ws.readyState === 1 /* OPEN */) {
366
+ try {
367
+ const cancelId = nextId()
368
+ this._ignoredResponseIds.add(cancelId)
369
+ // Safety-net eviction: if the executor's ack never
370
+ // arrives (e.g. the socket drops right after we
371
+ // send request.cancel), the normal cleanup path
372
+ // (deleting the id when its response lands) never
373
+ // fires and the entry would live in this set for
374
+ // the lifetime of the client. Bound it instead —
375
+ // DEFAULT_TIMEOUT_MS is already the ceiling every
376
+ // other in-flight call uses, so an ack that hasn't
377
+ // shown up by then isn't coming.
378
+ setTimeout(() => {
379
+ this._ignoredResponseIds.delete(cancelId)
380
+ }, DEFAULT_TIMEOUT_MS)
381
+ this._ws.send(JSON.stringify({
382
+ id: cancelId,
383
+ type: 'request.cancel',
384
+ params: { targetId: id },
385
+ }))
386
+ } catch (e) {
387
+ // Swallow — the user-visible failure mode is the
388
+ // AbortError below; a socket send failure here
389
+ // doesn't change client semantics.
390
+ }
391
+ }
392
+
393
+ reject(new DOMException('Aborted', 'AbortError'))
394
+ }
395
+ signal.addEventListener('abort', abortHandler, { once: true })
396
+ }
397
+
237
398
  if (this._ws && this._ws.readyState === 1 /* OPEN */) {
238
399
  this._ws.send(JSON.stringify(message))
239
400
  } else {
240
401
  this._pendingCalls.delete(id)
241
402
  clearTimeout(timer)
403
+ cleanup()
242
404
  reject(new RpcError(503, 'WebSocket not connected'))
243
405
  }
244
406
  })
@@ -284,6 +446,14 @@ export class ApiClient {
284
446
  }
285
447
  }
286
448
 
449
+ /** Register a callback that fires after a successful WebSocket reconnect.
450
+ * Does NOT fire on the initial connection — only on reconnects.
451
+ * Returns an unsubscribe function. */
452
+ onReconnect(callback: () => void): () => void {
453
+ this._reconnectCallbacks.add(callback)
454
+ return () => { this._reconnectCallbacks.delete(callback) }
455
+ }
456
+
287
457
  /** Close all open WebSocket connections and reject pending calls. */
288
458
  closeAll(): void {
289
459
  // Reject pending calls
@@ -294,5 +464,11 @@ export class ApiClient {
294
464
  this._pendingCalls.clear()
295
465
  this._closeWs()
296
466
  this._wsCallbacks.clear()
467
+ this._reconnectCallbacks.clear()
468
+ // Reset the first-connect gate so a reused client (closeAll() →
469
+ // later call()/subscribe() reopening via _ensureWs) does not fire
470
+ // freshly registered onReconnect callbacks on the initial open of
471
+ // the new connection — see the contract on onReconnect().
472
+ this._hasConnectedOnce = false
297
473
  }
298
474
  }
@@ -6,13 +6,29 @@ import type { TranscriptTurn } from "./TranscriptTurn";
6
6
  * SHACL subject classes. Shapes are resolved server-side from the
7
7
  * perspective's registered classes, so callers pass only the transcript.
8
8
  */
9
- export type RunInterpretationRequest = { uuid: string, transcript: Array<TranscriptTurn>,
9
+ export type RunInterpretationRequest = { uuid: string, transcript: Array<TranscriptTurn>,
10
10
  /**
11
11
  * URI namespace new instance identities are minted under, e.g. `soa://ext/`.
12
12
  */
13
- basePrefix: string,
13
+ basePrefix: string,
14
14
  /**
15
15
  * Local names of the subject classes to extract into (e.g. `["Task","Belief"]`).
16
16
  * `None`/empty selects all subject classes registered in the perspective.
17
17
  */
18
- classes: Array<string> | null, };
18
+ classes: Array<string> | null,
19
+ /**
20
+ * Optional parent-scope filter for the dedup lookup: when set, only
21
+ * existing instances of the target classes that live under this scope
22
+ * are candidates for upsert. `None` = whole-perspective dedup set (the
23
+ * pre-scope default). Same semantics as `AutoProcessorConfig.existingScope`.
24
+ */
25
+ existingScope?: any,
26
+ /**
27
+ * Optional parent-scope target for newly minted instances: when set,
28
+ * every base URI the pass CREATES is additionally linked as a child of
29
+ * `mintScope.id` via the scope's predicate. Upserts of pre-existing
30
+ * instances are NOT linked (would multi-parent unrelated graph state).
31
+ * Must be the `Raw` variant of `Scope` (id + predicate). Same semantics
32
+ * as `AutoProcessorConfig.mintScope`.
33
+ */
34
+ mintScope?: any, };
package/src/index.ts CHANGED
@@ -18,6 +18,8 @@ export * from "./perspectives/PerspectiveHandle";
18
18
  export * from "./perspectives/PerspectiveProxy";
19
19
  export * from "./perspectives/AutoProcessor";
20
20
  export * from "./perspectives/InterpretationModels";
21
+ export * from "./perspectives/FlowModels";
22
+ export * from "./perspectives/FlowInstance";
21
23
  export * from "./perspectives/SparqlBindings";
22
24
  export * from "./perspectives/WakerSubscriptionManager";
23
25
  export * from "./perspectives/PerspectiveDiff";
@@ -35,7 +37,7 @@ export * from "./ai/Tasks"
35
37
  export * from "./runtime/RuntimeTypes"
36
38
  export { Model as AIModel, ModelApi, TokenizerSource, LocalModel, ModelType, ModelApiInput, TokenizerSourceInput, LocalModelInput, ModelInput, VoiceActivityParamsInput } from "./ai/AITypes"
37
39
  export * from './shacl/SHACLShape'
38
- export { SHACLFlow, FlowState, FlowTransition, LinkPattern, FlowableCondition } from './shacl/SHACLFlow'
40
+ export { SHACLFlow, FlowState, FlowTransition, LinkPattern, ModelQuery, PropertyCondition, ConsensusRule } from './shacl/SHACLFlow'
39
41
  export * from './shacl/NodeExpression'
40
42
  export * from './shacl/builders'
41
43
  export { fileToDataUri } from './shacl/index'