@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,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, 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.
@@ -320,6 +359,14 @@ export declare class PerspectiveProxy {
320
359
  rejectInterpretation(base: string, property?: string): Promise<boolean>;
321
360
  /** Subscribe to this perspective's auto-processor step signals. */
322
361
  addAutoProcessorEventListener(cb: (event: AutoProcessorEvent) => void): Promise<void>;
362
+ /**
363
+ * Subscribe to this perspective's auto-processor neighbourhood-state
364
+ * events — fires when this executor claims / finishes / abandons a
365
+ * batch. Perspective-scoped, so a UI can render "someone is
366
+ * auto-processing this" without receiving the batch payload. See
367
+ * `AutoProcessorNeighbourhoodStateEvent`.
368
+ */
369
+ addAutoProcessorNeighbourhoodStateListener(cb: (event: AutoProcessorNeighbourhoodStateEvent) => void): Promise<void>;
323
370
  /**
324
371
  * Executes a Prolog query against the perspective's knowledge base.
325
372
  * This is a powerful way to find complex patterns in the graph.
@@ -343,7 +390,7 @@ export declare class PerspectiveProxy {
343
390
  * `);
344
391
  * ```
345
392
  */
346
- infer(query: string): Promise<any>;
393
+ infer(query: string, options?: CallOptions): Promise<any>;
347
394
  /**
348
395
  * Executes a SPARQL query against the perspective's link cache.
349
396
  * This allows powerful SQL-like queries on the link data stored in SPARQL.
@@ -352,15 +399,21 @@ export declare class PerspectiveProxy {
352
399
  * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
353
400
  * blocked for security reasons. Use the perspective's add/remove methods to modify links.
354
401
  *
355
- * @param query - SPARQL query string (read-only operations only)
356
- * @returns Query results as parsed JSON
357
- *
358
- * 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.
359
411
  *
360
- * @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)
361
414
  * @returns Query results as parsed JSON
362
415
  */
363
- querySparql<T = any>(query: string): Promise<T>;
416
+ querySparql<T = any>(query: string, options?: CallOptions): Promise<T>;
364
417
  /**
365
418
  * Execute a model query — the executor-side replacement for SPARQL query building + JS hydration.
366
419
  *
@@ -372,10 +425,41 @@ export declare class PerspectiveProxy {
372
425
  * @param queryJson - Structured query as JSON string
373
426
  * @returns Object with `instances` array and `totalCount`
374
427
  */
375
- modelQuery(className: string, queryJson: string): Promise<{
428
+ modelQuery(className: string, queryJson: string, options?: CallOptions): Promise<{
376
429
  instances: any[];
377
430
  totalCount: number;
378
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[]>>;
379
463
  /**
380
464
  * Evaluate property getters for a batch of instances in a single RPC call.
381
465
  * Returns a map of `{ instanceId: { prop: value, ... } }`.
@@ -594,18 +678,28 @@ export declare class PerspectiveProxy {
594
678
  setSingleTarget(link: Link, status?: LinkStatus): Promise<void>;
595
679
  /** Returns all the Social DNA flows defined in this perspective */
596
680
  sdnaFlows(): Promise<string[]>;
597
- /** 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
+ */
598
702
  availableFlows(exprAddr: string): Promise<string[]>;
599
- /** Starts the Social DNA flow @param flowName on the expression @param exprAddr */
600
- startFlow(flowName: string, exprAddr: string): Promise<void>;
601
- /** Returns all expressions in the given state of given Social DNA flow */
602
- expressionsInFlowState(flowName: string, flowState: number): Promise<string[]>;
603
- /** Returns the given expression's flow state with regard to given Social DNA flow */
604
- flowState(flowName: string, exprAddr: string): Promise<number>;
605
- /** Returns available action names, with regard to Social DNA flow and expression's flow state */
606
- flowActions(flowName: string, exprAddr: string): Promise<string[]>;
607
- /** Runs given Social DNA flow action */
608
- runFlowAction(flowName: string, exprAddr: string, actionName: string): Promise<void>;
609
703
  /** Returns the perspective's Social DNA code
610
704
  * This will return all SDNA code elements in an array.
611
705
  */
@@ -684,28 +778,27 @@ export declare class PerspectiveProxy {
684
778
  */
685
779
  addShacl(name: string, shape: SHACLShape): Promise<void>;
686
780
  /**
687
- * 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.
688
784
  */
689
785
  getShacl(name: string): Promise<SHACLShape | null>;
690
786
  /**
691
- * List the names of every SHACL shape stored in this Perspective, without fetching
692
- * each shape's full definition (properties, target class, etc.) — just the cheap
693
- * `ad4m://has_shacl` enumeration, one round trip regardless of how many shapes exist.
694
- * Use this to check which shapes are actually worth resolving via `getShacl()` before
695
- * 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).
696
788
  */
697
789
  getShaclNames(): Promise<string[]>;
698
790
  /**
699
- * Resolve just a shape's `sh:targetClass` by name, without fetching its properties —
700
- * two round trips (name → shapeUri, then shapeUri's own direct triples) instead of
701
- * `getShacl()`'s full walk (which also fetches every property sub-shape). Use this to
702
- * disambiguate a shape name that collides with another app's `@Model({ name })` string
703
- * (the bare `shacl://{name}` mapping ad4m-core uses is namespace-blind — see
704
- * `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.
705
797
  */
706
798
  getShaclTargetClass(name: string): Promise<string | undefined>;
707
799
  /**
708
- * 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.
709
802
  */
710
803
  getAllShacl(): Promise<Array<{
711
804
  name: string;
@@ -724,28 +817,26 @@ export declare class PerspectiveProxy {
724
817
  * ```typescript
725
818
  * import { SHACLFlow } from '@coasys/ad4m';
726
819
  *
727
- * const todoFlow = new SHACLFlow('TODO', 'todo://');
728
- * todoFlow.flowable = 'any';
729
- *
730
- * // Define states
731
- * todoFlow.addState({ name: 'ready', value: 0, stateCheck: { predicate: 'todo://state', target: 'todo://ready' }});
732
- * todoFlow.addState({ name: 'done', value: 1, stateCheck: { predicate: 'todo://state', target: 'todo://done' }});
733
- *
734
- * // Define start action
735
- * todoFlow.startAction = [{ action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }];
736
- *
737
- * // Define transitions
738
- * todoFlow.addTransition({
739
- * actionName: 'Complete',
740
- * fromState: 'ready',
741
- * toState: 'done',
742
- * actions: [
743
- * { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://done' },
744
- * { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
745
- * ]
746
- * });
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 };
747
838
  *
748
- * await perspective.addFlow('TODO', todoFlow);
839
+ * await perspective.addFlow('Delivery', deliveryFlow);
749
840
  * ```
750
841
  */
751
842
  addFlow(name: string, flow: SHACLFlow): Promise<void>;
@@ -769,7 +860,9 @@ export declare class PerspectiveProxy {
769
860
  * with the properties of the subject class.
770
861
  * @param exprAddr The address of the expression to be turned into a subject instance
771
862
  * @param initialValues Optional initial values for properties. If provided, these will be
772
- * 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.
773
866
  * @param batchId Optional batch ID for grouping operations. If provided, returns the expression address
774
867
  * instead of the subject proxy since the subject won't exist until the batch is committed.
775
868
  * @returns A proxy object for the created subject, or just the expression address if in batch mode