@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
@@ -115,13 +115,9 @@ __decorate([
115
115
  __metadata("design:type", String)
116
116
  ], AutoProcessorConfig.prototype, "mintScope", void 0);
117
117
  __decorate([
118
- Optional({ through: "ad4m://debug_mode", resolveLanguage: "literal" }),
118
+ Optional({ through: "ad4m://max_tool_calls" }),
119
119
  __metadata("design:type", String)
120
- ], AutoProcessorConfig.prototype, "debugMode", void 0);
121
- __decorate([
122
- Optional({ through: "ad4m://persist_debug", resolveLanguage: "literal" }),
123
- __metadata("design:type", String)
124
- ], AutoProcessorConfig.prototype, "persistDebug", void 0);
120
+ ], AutoProcessorConfig.prototype, "maxToolCalls", void 0);
125
121
  __decorate([
126
122
  Optional({ through: "ad4m://emit_debug_events", resolveLanguage: "literal" }),
127
123
  __metadata("design:type", String)
@@ -1,4 +1,4 @@
1
- import { ApiClient } from "../apiClient";
1
+ import { ApiClient, CallOptions } from "../apiClient";
2
2
  import { ExpressionRendered } from "../expression/Expression";
3
3
  import { ExpressionClient } from "../expression/ExpressionClient";
4
4
  import { Link, LinkExpressionInput, LinkExpression, LinkMutations, LinkExpressionMutations } from "../links/Links";
@@ -11,7 +11,7 @@ import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
11
11
  import { AIClient } from "../ai/AIClient";
12
12
  import { AllInstancesResult } from "../model/types";
13
13
  import type { TranscriptTurn } from "../generated/api";
14
- import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope } from "./AutoProcessor";
14
+ import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
15
15
  export type PerspectiveHandleCallback = (perspective: PerspectiveHandle) => null;
16
16
  export type UuidCallback = (uuid: string) => null;
17
17
  export type LinkCallback = (link: LinkExpression) => null;
@@ -27,9 +27,9 @@ export declare class PerspectiveClient {
27
27
  byUUID(uuid: string): Promise<PerspectiveProxy | null>;
28
28
  snapshotByUUID(uuid: string): Promise<Perspective | null>;
29
29
  publishSnapshotByUUID(uuid: string): Promise<string | null>;
30
- queryLinks(uuid: string, query: LinkQuery): Promise<LinkExpression[]>;
31
- queryProlog(uuid: string, query: string): Promise<unknown>;
32
- querySparql<T = any>(uuid: string, query: string): Promise<T>;
30
+ queryLinks(uuid: string, query: LinkQuery, options?: CallOptions): Promise<LinkExpression[]>;
31
+ queryProlog(uuid: string, query: string, options?: CallOptions): Promise<unknown>;
32
+ querySparql<T = any>(uuid: string, query: string, options?: CallOptions): Promise<T>;
33
33
  subscribeQuery(uuid: string, query: string): Promise<{
34
34
  subscriptionId: string;
35
35
  result: AllInstancesResult;
@@ -39,7 +39,8 @@ export declare class PerspectiveClient {
39
39
  subscribeToQueryUpdates(subscriptionId: string, onData: (result: AllInstancesResult) => void): () => void;
40
40
  keepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean>;
41
41
  disposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
42
- modelQuery(uuid: string, className: string, queryJson: string): Promise<any>;
42
+ modelQuery(uuid: string, className: string, queryJson: string, options?: CallOptions): Promise<any>;
43
+ subjectClassesOf(uuid: string, uris: string[]): Promise<Record<string, string[]>>;
43
44
  evaluateGetters(uuid: string, className: string, instanceIds: string[], propertyNames?: string[]): Promise<Record<string, Record<string, any>>>;
44
45
  modelSubscribe(uuid: string, className: string, queryJson: string): Promise<{
45
46
  subscriptionId: string;
@@ -71,7 +72,23 @@ export declare class PerspectiveClient {
71
72
  * `mintScope.id` via its predicate (upserts of pre-existing instances
72
73
  * are NOT re-parented — same rule as the watcher).
73
74
  */
74
- runInterpretation(uuid: string, transcript: TranscriptTurn[], basePrefix: string, classes?: string[], existingScope?: RawScope, mintScope?: RawScope): Promise<string[]>;
75
+ runInterpretation(uuid: string, transcript: TranscriptTurn[], basePrefix: string, classes?: string[], existingScope?: RawScope, mintScope?: RawScope, observe?: RunInterpretationObserveOptions): Promise<string[]>;
76
+ /**
77
+ * Tool-calling counterpart to {@link runInterpretation}. The LLM sees a
78
+ * live per-class tool surface (`{Class}_query`, `{Class}_propose_create`,
79
+ * `{Class}_propose_link_child`, …) and drives the extraction via tool
80
+ * calls; buffered proposals drain through the same overlay gate the
81
+ * single-shot path uses.
82
+ *
83
+ * `maxToolCalls` bounds the loop and MUST be > 0 — zero would collapse
84
+ * the harness to a no-op final-answer step; use {@link runInterpretation}
85
+ * for the classic single-shot path.
86
+ *
87
+ * Same 20-minute RPC timeout as the single-shot path — an LLM loop
88
+ * that calls several tools can legitimately take longer than one plain
89
+ * generation.
90
+ */
91
+ runInterpretationWithHarness(uuid: string, transcript: TranscriptTurn[], basePrefix: string, maxToolCalls: number, classes?: string[], modelOverride?: string, existingScope?: RawScope, observationId?: string, emitDebugEvents?: boolean): Promise<string[]>;
75
92
  /**
76
93
  * Register a neighbourhood auto-processor on this perspective. The executor's
77
94
  * watch loop then runs interpretation automatically over new source items
@@ -81,6 +98,8 @@ export declare class PerspectiveClient {
81
98
  * Returns the processor id.
82
99
  */
83
100
  addAutoProcessor(uuid: string, config: AddAutoProcessorConfig): Promise<string>;
101
+ /** Delete an auto-processor's config. `false` when there was none to delete. */
102
+ removeAutoProcessor(uuid: string, processorId: string): Promise<boolean>;
84
103
  /** Pending interpretation overlays (LLM suggestions awaiting human accept/reject). */
85
104
  interpretationOverlays(uuid: string): Promise<InterpretationOverlayInfo[]>;
86
105
  /** Accept an overlay's suggestion(s): the LLM value becomes the real value and
@@ -122,6 +141,45 @@ export declare class PerspectiveClient {
122
141
  executeCommands(uuid: string, commands: string, expression: string, parameters: string, batchId?: string): Promise<boolean>;
123
142
  createSubject(uuid: string, subjectClass: string, expressionAddress: string, initialValues?: string, batchId?: string): Promise<boolean>;
124
143
  getSubjectData(uuid: string, subjectClass: string, expressionAddress: string): Promise<string>;
144
+ /** List the names of every SHACL shape stored in a perspective (one RPC call). */
145
+ getShaclNames(uuid: string): Promise<string[]>;
146
+ /**
147
+ * Resolve a shape's `sh:targetClass` by name (one RPC call).
148
+ *
149
+ * Returns `undefined` when the shape (or its `sh://targetClass` edge) is
150
+ * absent — unified with `PerspectiveProxy.getShaclTargetClass` so callers
151
+ * see a single "not found" representation across both layers. The
152
+ * executor wire format is still `null` (see `perspective.getShaclTargetClass`
153
+ * in `perspectives_ws.rs`); this method maps that at the boundary rather
154
+ * than pushing the null one layer further up. PR #935 review r3897752023.
155
+ */
156
+ getShaclTargetClass(uuid: string, name: string): Promise<string | undefined>;
157
+ /**
158
+ * Retrieve a single SHACL shape's link triples by name (one RPC call).
159
+ * Returns `{shapeUri, links}` for reconstruction via `SHACLShape.fromLinks()`,
160
+ * or `null` if no shape with that name exists.
161
+ */
162
+ getShacl(uuid: string, name: string): Promise<{
163
+ shapeUri: string;
164
+ links: Array<{
165
+ source: string;
166
+ predicate: string;
167
+ target: string;
168
+ }>;
169
+ } | null>;
170
+ /**
171
+ * Retrieve all SHACL shapes in one call. Returns an array of
172
+ * `{name, shapeUri, links}` — one entry per shape (one RPC call).
173
+ */
174
+ getAllShacl(uuid: string): Promise<Array<{
175
+ name: string;
176
+ shapeUri: string;
177
+ links: Array<{
178
+ source: string;
179
+ predicate: string;
180
+ target: string;
181
+ }>;
182
+ }>>;
125
183
  getExpression(expressionURI: string): Promise<ExpressionRendered>;
126
184
  createExpression(content: unknown, languageAddress: string): Promise<string>;
127
185
  addPerspectiveAddedListener(cb: PerspectiveHandleCallback): void;
@@ -141,4 +199,7 @@ export declare class PerspectiveClient {
141
199
  getNeighbourhoodProxy(uuid: string): NeighbourhoodProxy;
142
200
  createBatch(uuid: string): Promise<string>;
143
201
  commitBatch(uuid: string, batchId: string): Promise<LinkExpressionMutations>;
202
+ /** Register a callback that fires after a successful WebSocket reconnect.
203
+ * Passes through to ApiClient.onReconnect(). Returns an unsubscribe function. */
204
+ onReconnect(callback: () => void): () => void;
144
205
  }
@@ -87,7 +87,7 @@ export class PerspectiveClient {
87
87
  async publishSnapshotByUUID(uuid) {
88
88
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.publishSnapshot', { uuid });
89
89
  }
90
- async queryLinks(uuid, query) {
90
+ async queryLinks(uuid, query, options) {
91
91
  const params = { uuid };
92
92
  if (query.source)
93
93
  params.source = query.source;
@@ -101,14 +101,14 @@ export class PerspectiveClient {
101
101
  params.untilDate = query.untilDate instanceof Date ? query.untilDate.toISOString() : String(query.untilDate);
102
102
  if (query.limit !== undefined)
103
103
  params.limit = query.limit;
104
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.queryLinks', params);
104
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.queryLinks', params, options);
105
105
  }
106
- async queryProlog(uuid, query) {
107
- const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.queryProlog', { uuid, query });
106
+ async queryProlog(uuid, query, options) {
107
+ const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.queryProlog', { uuid, query }, options);
108
108
  return JSON.parse(result);
109
109
  }
110
- async querySparql(uuid, query) {
111
- const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.querySparql', { uuid, engine: 'sparql', query });
110
+ async querySparql(uuid, query, options) {
111
+ const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.querySparql', { uuid, engine: 'sparql', query }, options);
112
112
  return JSON.parse(result);
113
113
  }
114
114
  async subscribeQuery(uuid, query) {
@@ -148,10 +148,13 @@ export class PerspectiveClient {
148
148
  }
149
149
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.disposeQuery', { uuid, subscriptionId });
150
150
  }
151
- async modelQuery(uuid, className, queryJson) {
152
- const resultJson = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.modelQuery', { uuid, class_name: className, query_json: queryJson });
151
+ async modelQuery(uuid, className, queryJson, options) {
152
+ const resultJson = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.modelQuery', { uuid, class_name: className, query_json: queryJson }, options);
153
153
  return JSON.parse(resultJson);
154
154
  }
155
+ async subjectClassesOf(uuid, uris) {
156
+ return await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.subjectClassesOf', { uuid, uris });
157
+ }
155
158
  async evaluateGetters(uuid, className, instanceIds, propertyNames) {
156
159
  const resultJson = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.evaluateGetters', {
157
160
  uuid,
@@ -209,9 +212,55 @@ export class PerspectiveClient {
209
212
  * `mintScope.id` via its predicate (upserts of pre-existing instances
210
213
  * are NOT re-parented — same rule as the watcher).
211
214
  */
212
- async runInterpretation(uuid, transcript, basePrefix, classes, existingScope, mintScope) {
215
+ async runInterpretation(uuid, transcript, basePrefix, classes, existingScope, mintScope, observe) {
213
216
  const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000;
214
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', { uuid, transcript, basePrefix, classes, existingScope, mintScope }, RUN_INTERPRETATION_TIMEOUT_MS);
217
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', {
218
+ uuid, transcript, basePrefix, classes, existingScope, mintScope,
219
+ // Spread rather than always-present, so a client talking to a pre-#903
220
+ // executor sends exactly the params it sent before. `serde` would ignore
221
+ // the extra keys anyway; keeping the wire identical means a bug report
222
+ // from an older node cannot be about these.
223
+ ...(observe ? {
224
+ observationId: observe.observationId,
225
+ emitDebugEvents: observe.emitDebugEvents ?? false,
226
+ } : {}),
227
+ }, { timeoutMs: RUN_INTERPRETATION_TIMEOUT_MS });
228
+ }
229
+ /**
230
+ * Tool-calling counterpart to {@link runInterpretation}. The LLM sees a
231
+ * live per-class tool surface (`{Class}_query`, `{Class}_propose_create`,
232
+ * `{Class}_propose_link_child`, …) and drives the extraction via tool
233
+ * calls; buffered proposals drain through the same overlay gate the
234
+ * single-shot path uses.
235
+ *
236
+ * `maxToolCalls` bounds the loop and MUST be > 0 — zero would collapse
237
+ * the harness to a no-op final-answer step; use {@link runInterpretation}
238
+ * for the classic single-shot path.
239
+ *
240
+ * Same 20-minute RPC timeout as the single-shot path — an LLM loop
241
+ * that calls several tools can legitimately take longer than one plain
242
+ * generation.
243
+ */
244
+ async runInterpretationWithHarness(uuid, transcript, basePrefix, maxToolCalls, classes, modelOverride, existingScope,
245
+ // Optional live-debug event surface — same shape/semantics as the
246
+ // single-shot `runInterpretation`. `observationId` names the
247
+ // `processor_id` + `batch_key` on emitted `ToolCall` / `ToolResult`
248
+ // events so a subscribed UI can correlate them to this pass.
249
+ // `emitDebugEvents` is a dead-letter without an observationId
250
+ // (nothing to key against); the server gates on both.
251
+ observationId, emitDebugEvents) {
252
+ const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000;
253
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretationWithHarness', {
254
+ uuid,
255
+ transcript,
256
+ basePrefix,
257
+ maxToolCalls,
258
+ classes,
259
+ modelOverride,
260
+ existingScope,
261
+ observationId,
262
+ emitDebugEvents,
263
+ }, { timeoutMs: RUN_INTERPRETATION_TIMEOUT_MS });
215
264
  }
216
265
  /**
217
266
  * Register a neighbourhood auto-processor on this perspective. The executor's
@@ -224,6 +273,10 @@ export class PerspectiveClient {
224
273
  async addAutoProcessor(uuid, config) {
225
274
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addAutoProcessor', { uuid, ...config });
226
275
  }
276
+ /** Delete an auto-processor's config. `false` when there was none to delete. */
277
+ async removeAutoProcessor(uuid, processorId) {
278
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeAutoProcessor', { uuid, processorId });
279
+ }
227
280
  /** Pending interpretation overlays (LLM suggestions awaiting human accept/reject). */
228
281
  async interpretationOverlays(uuid) {
229
282
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.interpretationOverlays', { uuid });
@@ -306,6 +359,43 @@ export class PerspectiveClient {
306
359
  async getSubjectData(uuid, subjectClass, expressionAddress) {
307
360
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getSubjectData', { uuid, subjectClass, expressionAddress });
308
361
  }
362
+ // ── SHACL resolution (server-side) ─────────────────────────────────────────
363
+ // These methods delegate shape resolution to the executor, which reads links
364
+ // from its local store in-process. Each call replaces the multi-round-trip
365
+ // `queryLinks` sequences the old PerspectiveProxy methods performed.
366
+ /** List the names of every SHACL shape stored in a perspective (one RPC call). */
367
+ async getShaclNames(uuid) {
368
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getShaclNames', { uuid });
369
+ }
370
+ /**
371
+ * Resolve a shape's `sh:targetClass` by name (one RPC call).
372
+ *
373
+ * Returns `undefined` when the shape (or its `sh://targetClass` edge) is
374
+ * absent — unified with `PerspectiveProxy.getShaclTargetClass` so callers
375
+ * see a single "not found" representation across both layers. The
376
+ * executor wire format is still `null` (see `perspective.getShaclTargetClass`
377
+ * in `perspectives_ws.rs`); this method maps that at the boundary rather
378
+ * than pushing the null one layer further up. PR #935 review r3897752023.
379
+ */
380
+ async getShaclTargetClass(uuid, name) {
381
+ const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getShaclTargetClass', { uuid, name });
382
+ return result ?? undefined;
383
+ }
384
+ /**
385
+ * Retrieve a single SHACL shape's link triples by name (one RPC call).
386
+ * Returns `{shapeUri, links}` for reconstruction via `SHACLShape.fromLinks()`,
387
+ * or `null` if no shape with that name exists.
388
+ */
389
+ async getShacl(uuid, name) {
390
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getShacl', { uuid, name });
391
+ }
392
+ /**
393
+ * Retrieve all SHACL shapes in one call. Returns an array of
394
+ * `{name, shapeUri, links}` — one entry per shape (one RPC call).
395
+ */
396
+ async getAllShacl(uuid) {
397
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getAllShacl', { uuid });
398
+ }
309
399
  // ExpressionClient functions, needed for Subjects:
310
400
  async getExpression(expressionURI) {
311
401
  return await __classPrivateFieldGet(this, _PerspectiveClient_expressionClient, "f").get(expressionURI);
@@ -427,5 +517,10 @@ export class PerspectiveClient {
427
517
  async commitBatch(uuid, batchId) {
428
518
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.commitBatch', { uuid, batchId });
429
519
  }
520
+ /** Register a callback that fires after a successful WebSocket reconnect.
521
+ * Passes through to ApiClient.onReconnect(). Returns an unsubscribe function. */
522
+ onReconnect(callback) {
523
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").onReconnect(callback);
524
+ }
430
525
  }
431
526
  _PerspectiveClient_apiClient = new WeakMap(), _PerspectiveClient_perspectiveAddedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveUpdatedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveRemovedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveSyncStateChangeCallbacks = new WeakMap(), _PerspectiveClient_expressionClient = new WeakMap(), _PerspectiveClient_neighbourhoodClient = new WeakMap(), _PerspectiveClient_aiClient = new WeakMap(), _PerspectiveClient_unsubscribers = new WeakMap(), _PerspectiveClient_linkUnsubscribers = new WeakMap(), _PerspectiveClient_querySubscriptionUnsubscribers = new WeakMap();
@@ -1,4 +1,5 @@
1
1
  import { LinkCallback, PerspectiveClient, SyncStateChangeCallback } from "./PerspectiveClient";
2
+ import { CallOptions } from "../apiClient";
2
3
  import { Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkMutations } from "../links/Links";
3
4
  import { LinkQuery } from "./LinkQuery";
4
5
  import { PerspectiveHandle, PerspectiveState } from './PerspectiveHandle';
@@ -11,7 +12,7 @@ import { AllInstancesResult } from "../model/types";
11
12
  import type { TranscriptTurn } from "../generated/api";
12
13
  import { SHACLShape } from "../shacl/SHACLShape";
13
14
  import { SHACLFlow } from "../shacl/SHACLFlow";
14
- import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo } from "./AutoProcessor";
15
+ import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
15
16
  type QueryCallback = (result: AllInstancesResult) => void;
16
17
  /** Proxy object for a subscribed Prolog query that provides real-time updates
17
18
  *
@@ -279,7 +280,7 @@ export declare class PerspectiveProxy {
279
280
  * });
280
281
  * ```
281
282
  */
282
- get(query: LinkQuery): Promise<LinkExpression[]>;
283
+ get(query: LinkQuery, options?: CallOptions): Promise<LinkExpression[]>;
283
284
  /**
284
285
  * Runs generic LLM interpretation over a conversation transcript, turning it
285
286
  * into typed instances of this perspective's own SHACL subject classes
@@ -293,7 +294,29 @@ export declare class PerspectiveProxy {
293
294
  * @param basePrefix URI namespace for new instance identities, e.g. `soa://ext/`
294
295
  * @param classes local names of the subject classes to extract into; omit for all
295
296
  */
296
- runInterpretation(transcript: TranscriptTurn[], basePrefix: string, classes?: string[]): Promise<string[]>;
297
+ runInterpretation(transcript: TranscriptTurn[], basePrefix: string, classes?: string[], options?: {
298
+ existingScope?: RawScope;
299
+ mintScope?: RawScope;
300
+ /** Report progress while the pass runs — see {@link RunInterpretationObserveOptions}. */
301
+ observe?: RunInterpretationObserveOptions;
302
+ }): Promise<string[]>;
303
+ /**
304
+ * Harness-dispatched interpretation pass over this perspective (design v3
305
+ * §6 — the tool-calling counterpart to {@link runInterpretation}). The LLM
306
+ * sees a live per-class tool surface (`{Class}_query`, `{Class}_get`,
307
+ * `{Class}_propose_create`, `{Class}_propose_link_child`, …) and drives
308
+ * the extraction via tool calls; buffered proposals drain through the
309
+ * same overlay gate the single-shot path uses.
310
+ *
311
+ * @param transcript ordered `{ speaker, text }` turns
312
+ * @param basePrefix URI namespace new instance identities are minted under
313
+ * @param maxToolCalls upper bound on tool calls the harness will make in
314
+ * one pass (must be > 0 — use {@link runInterpretation} for the
315
+ * classic single-shot path)
316
+ * @param classes local names of the subject classes to extract into; omit for all
317
+ * @param modelOverride optional model override; omit for the default LLM
318
+ */
319
+ runInterpretationWithHarness(transcript: TranscriptTurn[], basePrefix: string, maxToolCalls: number, classes?: string[], modelOverride?: string, observationId?: string, emitDebugEvents?: boolean): Promise<string[]>;
297
320
  /**
298
321
  * Register a neighbourhood auto-processor on this perspective. The executor
299
322
  * then runs interpretation automatically over new source items (like Flux
@@ -301,6 +324,22 @@ export declare class PerspectiveProxy {
301
324
  * processor id. Subscribe to progress via {@link addAutoProcessorEventListener}.
302
325
  */
303
326
  addAutoProcessor(config: AddAutoProcessorConfig): Promise<string>;
327
+ /**
328
+ * Stop an auto-processor by deleting its config.
329
+ *
330
+ * The registration is data — the watch loop reads the processor set back out of the
331
+ * perspective's graph on every tick — so deleting the config is what stops it, and there is
332
+ * nothing else to unregister. The config is `Shared`, so this stops the processor for the
333
+ * neighbourhood rather than only for this peer.
334
+ *
335
+ * Resolves `true` when there was a processor to remove and `false` when there was not; a
336
+ * processor another peer has already removed is not an error.
337
+ *
338
+ * The processor's `InterpretationRun` nodes stay: they are the record of what it did and the
339
+ * processed-turn cursor, so a processor later registered under the same id resumes where this
340
+ * one left off rather than re-reading every turn.
341
+ */
342
+ removeAutoProcessor(processorId: string): Promise<boolean>;
304
343
  /**
305
344
  * Pending interpretation overlays on this perspective — LLM suggestions the
306
345
  * §4 divergence gate staged rather than applied, awaiting human accept/reject.
@@ -351,7 +390,7 @@ export declare class PerspectiveProxy {
351
390
  * `);
352
391
  * ```
353
392
  */
354
- infer(query: string): Promise<any>;
393
+ infer(query: string, options?: CallOptions): Promise<any>;
355
394
  /**
356
395
  * Executes a SPARQL query against the perspective's link cache.
357
396
  * This allows powerful SQL-like queries on the link data stored in SPARQL.
@@ -360,15 +399,21 @@ export declare class PerspectiveProxy {
360
399
  * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
361
400
  * blocked for security reasons. Use the perspective's add/remove methods to modify links.
362
401
  *
363
- * @param query - SPARQL query string (read-only operations only)
364
- * @returns Query results as parsed JSON
365
- *
366
- * Executes a SPARQL query against the perspective's RDF (Oxigraph) store.
402
+ * **Cancellation:** Pass `{ signal }` from an `AbortController` to abort
403
+ * an in-flight query. The executor receives `request.cancel` over the
404
+ * WebSocket and short-circuits the JSON reply. Caveat: Oxigraph itself
405
+ * cannot be interrupted mid-evaluation, so an already-running scan will
406
+ * keep its blocking thread busy until it completes; what's saved is the
407
+ * serialise + network + client-deserialise tax on the result. Aborted
408
+ * calls reject with `DOMException('Aborted', 'AbortError')` — match
409
+ * `fetch()` for handling. Cached results bypass the round-trip entirely
410
+ * and are returned synchronously, ignoring the signal.
367
411
  *
368
- * @param query - SPARQL query string
412
+ * @param query - SPARQL query string (read-only operations only)
413
+ * @param options - Optional call options (e.g. AbortSignal for cancellation)
369
414
  * @returns Query results as parsed JSON
370
415
  */
371
- querySparql<T = any>(query: string): Promise<T>;
416
+ querySparql<T = any>(query: string, options?: CallOptions): Promise<T>;
372
417
  /**
373
418
  * Execute a model query — the executor-side replacement for SPARQL query building + JS hydration.
374
419
  *
@@ -380,10 +425,41 @@ export declare class PerspectiveProxy {
380
425
  * @param queryJson - Structured query as JSON string
381
426
  * @returns Object with `instances` array and `totalCount`
382
427
  */
383
- modelQuery(className: string, queryJson: string): Promise<{
428
+ modelQuery(className: string, queryJson: string, options?: CallOptions): Promise<{
384
429
  instances: any[];
385
430
  totalCount: number;
386
431
  }>;
432
+ /** Resolve each URI to the names of every subject class it is an instance of.
433
+ *
434
+ * The counterpart of {@link isSubjectInstance}, which asks the same question
435
+ * one class at a time. Without this, finding the class of an arbitrary URI
436
+ * meant looping over every registered class — a round trip each — and doing
437
+ * it again for every URI.
438
+ *
439
+ * Class membership in AD4M is structural — a URI belongs to a class when it
440
+ * carries that class's flags and required properties — so membership is **not
441
+ * exclusive**: an instance conforms to its parent classes, and to any
442
+ * unrelated class whose required set happens to be a subset of what it
443
+ * carries. Every match is returned.
444
+ *
445
+ * The list is ordered **most specific first**, meaning by the number of
446
+ * triples the class requires — a subclass requires everything its parent does
447
+ * and more — with ties broken alphabetically so that every peer answers
448
+ * identically. A caller that can only act on one class should take
449
+ * `classes[0]`, but that head is only a heuristic: it is arbitrary between two
450
+ * unrelated classes requiring the same number of triples, which is exactly
451
+ * the case the full list exists to expose.
452
+ *
453
+ * A URI is **absent from the result** when no *registered* class matched it.
454
+ * That covers two situations, and nothing here separates them: the URI may
455
+ * not be a subject instance at all, or it may be an instance of a class this
456
+ * perspective has not registered. Absence is used rather than an empty list
457
+ * because an empty list would claim the stronger thing — that the URI belongs
458
+ * to no class — which this cannot know.
459
+ *
460
+ * @param uris The expression URIs to classify.
461
+ */
462
+ subjectClassesOf(uris: string[]): Promise<Record<string, string[]>>;
387
463
  /**
388
464
  * Evaluate property getters for a batch of instances in a single RPC call.
389
465
  * Returns a map of `{ instanceId: { prop: value, ... } }`.
@@ -602,18 +678,28 @@ export declare class PerspectiveProxy {
602
678
  setSingleTarget(link: Link, status?: LinkStatus): Promise<void>;
603
679
  /** Returns all the Social DNA flows defined in this perspective */
604
680
  sdnaFlows(): Promise<string[]>;
605
- /** Returns all Social DNA flows that can be started from the given expression */
681
+ /**
682
+ * Returns all Social DNA flows that can be started from the given expression.
683
+ *
684
+ * Post-`flowable` retirement: a flow is a candidate iff its `inputTypes`
685
+ * declaration is compatible with the expression. Matching rules:
686
+ * - Empty `inputTypes` or one containing the `"any"` wildcard → always
687
+ * matches (same behaviour as the legacy `flowable === "any"` case).
688
+ * - Otherwise, at least one of the expression's registered subject-class
689
+ * URIs (resolved via {@link subjectClassesOf}) must appear in
690
+ * `inputTypes`. This is the concrete-type match the design doc's §5
691
+ * spawn engine calls for; without it, a flow declaring
692
+ * `inputTypes: ["Task"]` was previously *never* returned by
693
+ * `availableFlows("some-task-uri")` — the entire point of typed
694
+ * flows was silently unreachable (James PR #929 J#3).
695
+ *
696
+ * The expression is classified against the perspective's registered
697
+ * classes only. An expression whose class is not registered on this
698
+ * perspective matches no typed flow (absence, not falsehood — same
699
+ * discipline as {@link subjectClassesOf}); typed flows requiring
700
+ * unknown classes are still returned to their untyped-caller peers.
701
+ */
606
702
  availableFlows(exprAddr: string): Promise<string[]>;
607
- /** Starts the Social DNA flow @param flowName on the expression @param exprAddr */
608
- startFlow(flowName: string, exprAddr: string): Promise<void>;
609
- /** Returns all expressions in the given state of given Social DNA flow */
610
- expressionsInFlowState(flowName: string, flowState: number): Promise<string[]>;
611
- /** Returns the given expression's flow state with regard to given Social DNA flow */
612
- flowState(flowName: string, exprAddr: string): Promise<number>;
613
- /** Returns available action names, with regard to Social DNA flow and expression's flow state */
614
- flowActions(flowName: string, exprAddr: string): Promise<string[]>;
615
- /** Runs given Social DNA flow action */
616
- runFlowAction(flowName: string, exprAddr: string, actionName: string): Promise<void>;
617
703
  /** Returns the perspective's Social DNA code
618
704
  * This will return all SDNA code elements in an array.
619
705
  */
@@ -692,28 +778,27 @@ export declare class PerspectiveProxy {
692
778
  */
693
779
  addShacl(name: string, shape: SHACLShape): Promise<void>;
694
780
  /**
695
- * Retrieve a SHACL shape by name from this Perspective
781
+ * Retrieve a SHACL shape by name from this Perspective (one RPC call).
782
+ * The executor resolves the full shape (including property sub-shapes)
783
+ * in-process and returns link triples for client-side reconstruction.
696
784
  */
697
785
  getShacl(name: string): Promise<SHACLShape | null>;
698
786
  /**
699
- * List the names of every SHACL shape stored in this Perspective, without fetching
700
- * each shape's full definition (properties, target class, etc.) — just the cheap
701
- * `ad4m://has_shacl` enumeration, one round trip regardless of how many shapes exist.
702
- * Use this to check which shapes are actually worth resolving via `getShacl()` before
703
- * paying for each one's full (multi-round-trip) fetch.
787
+ * List the names of every SHACL shape stored in this Perspective (one RPC call).
704
788
  */
705
789
  getShaclNames(): Promise<string[]>;
706
790
  /**
707
- * Resolve just a shape's `sh:targetClass` by name, without fetching its properties —
708
- * two round trips (name → shapeUri, then shapeUri's own direct triples) instead of
709
- * `getShacl()`'s full walk (which also fetches every property sub-shape). Use this to
710
- * disambiguate a shape name that collides with another app's `@Model({ name })` string
711
- * (the bare `shacl://{name}` mapping ad4m-core uses is namespace-blind — see
712
- * `getShaclNames()` callers for why that matters) before paying for a full fetch.
791
+ * Resolve a shape's `sh:targetClass` by name (one RPC call).
792
+ *
793
+ * `PerspectiveClient.getShaclTargetClass` now returns `undefined` on
794
+ * "not found" already (see review r3897752023 — the null→undefined
795
+ * coercion used to happen here and be duplicated one layer down),
796
+ * so this method is a pure passthrough.
713
797
  */
714
798
  getShaclTargetClass(name: string): Promise<string | undefined>;
715
799
  /**
716
- * Get all SHACL shapes stored in this Perspective
800
+ * Get all SHACL shapes stored in this Perspective (one RPC call).
801
+ * The executor resolves all shapes in-process and returns them in bulk.
717
802
  */
718
803
  getAllShacl(): Promise<Array<{
719
804
  name: string;
@@ -732,28 +817,26 @@ export declare class PerspectiveProxy {
732
817
  * ```typescript
733
818
  * import { SHACLFlow } from '@coasys/ad4m';
734
819
  *
735
- * const todoFlow = new SHACLFlow('TODO', 'todo://');
736
- * todoFlow.flowable = 'any';
737
- *
738
- * // Define states
739
- * todoFlow.addState({ name: 'ready', value: 0, stateCheck: { predicate: 'todo://state', target: 'todo://ready' }});
740
- * todoFlow.addState({ name: 'done', value: 1, stateCheck: { predicate: 'todo://state', target: 'todo://done' }});
741
- *
742
- * // Define start action
743
- * todoFlow.startAction = [{ action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }];
744
- *
745
- * // Define transitions
746
- * todoFlow.addTransition({
747
- * actionName: 'Complete',
748
- * fromState: 'ready',
749
- * toState: 'done',
750
- * actions: [
751
- * { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://done' },
752
- * { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
753
- * ]
754
- * });
820
+ * const deliveryFlow = new SHACLFlow('Delivery', 'delivery://');
821
+ * deliveryFlow.inputTypes = ['Task'];
822
+ * deliveryFlow.interpretationHint =
823
+ * 'Advance a Task through delivery: Identified → Scoped → InProgress → Review → Done.';
824
+ *
825
+ * deliveryFlow.addState({ name: 'Identified', value: 0 });
826
+ * deliveryFlow.addState({ name: 'Scoped', value: 1 });
827
+ * deliveryFlow.addState({ name: 'InProgress', value: 2 });
828
+ * deliveryFlow.addState({ name: 'Review', value: 3 });
829
+ * deliveryFlow.addState({ name: 'Done', value: 4 });
830
+ *
831
+ * deliveryFlow.addTransition({ actionName: 'Scope', fromState: 'Identified', toState: 'Scoped', actions: [] });
832
+ * deliveryFlow.addTransition({ actionName: 'Start', fromState: 'Scoped', toState: 'InProgress', actions: [] });
833
+ * deliveryFlow.addTransition({ actionName: 'Submit', fromState: 'InProgress', toState: 'Review', actions: [] });
834
+ * deliveryFlow.addTransition({ actionName: 'Accept', fromState: 'Review', toState: 'Done', actions: [] });
835
+ *
836
+ * // Optional: n distinct DIDs must co-sign a proposal before it fires.
837
+ * deliveryFlow.consensusRule = { n: 2 };
755
838
  *
756
- * await perspective.addFlow('TODO', todoFlow);
839
+ * await perspective.addFlow('Delivery', deliveryFlow);
757
840
  * ```
758
841
  */
759
842
  addFlow(name: string, flow: SHACLFlow): Promise<void>;
@@ -777,7 +860,9 @@ export declare class PerspectiveProxy {
777
860
  * with the properties of the subject class.
778
861
  * @param exprAddr The address of the expression to be turned into a subject instance
779
862
  * @param initialValues Optional initial values for properties. If provided, these will be
780
- * merged with constructor actions for better performance.
863
+ * merged with constructor actions for better performance. A collection property accepts
864
+ * an array value and stores one entry per element; scalar properties store arrays/objects
865
+ * as a single JSON value.
781
866
  * @param batchId Optional batch ID for grouping operations. If provided, returns the expression address
782
867
  * instead of the subject proxy since the subject won't exist until the batch is committed.
783
868
  * @returns A proxy object for the created subject, or just the expression address if in batch mode