@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
@@ -16,7 +16,7 @@
16
16
  */
17
17
 
18
18
  import { Ad4mModel } from "../model/Ad4mModel";
19
- import { Flag, HasMany, Optional, Property } from "../model/decorators";
19
+ import { HasMany, Optional, Property } from "../model/decorators";
20
20
  import { Model } from "../model/decorators";
21
21
 
22
22
  // ── AutoProcessorConfig ─────────────────────────────────────────────────────
@@ -24,12 +24,19 @@ import { Model } from "../model/decorators";
24
24
  // One node per registered processor; the node URI is
25
25
  // `ad4m://autoprocessor/<processorId>`.
26
26
 
27
- @Model({ name: "AutoProcessorConfig" })
27
+ // Model name = "AutoProcessor" (NOT "AutoProcessorConfig") to match the Rust
28
+ // hardwired subject class in `perspectives/auto_processor/config.rs` — that
29
+ // alignment is what the SDNA parity test in
30
+ // `tests/js/tests/model/interpretation-models.test.ts` guards. The TS class
31
+ // symbol keeps the `Config` suffix for readability (`AutoProcessorConfig` reads
32
+ // better than a bare `AutoProcessor` for an "instances of the config record"
33
+ // query), but the on-graph subject class it registers is `AutoProcessor`.
34
+ @Model({ name: "AutoProcessor" })
28
35
  export class AutoProcessorConfig extends Ad4mModel {
29
- @Flag({ through: "rdf://type", value: "ad4m://AutoProcessor" })
30
- type: string = "ad4m://AutoProcessor";
31
-
32
36
  /** Unique processor id — the dedup key for auto-processor instances. */
37
+ // First-declared property: `buildSHACL` derives the shape namespace from
38
+ // its `through` prefix, so `ad4m://processor_id` → `ad4m://` → target_class
39
+ // `ad4m://AutoProcessor` (matches Rust `AUTO_PROCESSOR_TARGET_CLASS`).
33
40
  @Property({ through: "ad4m://processor_id", required: true, identity: true })
34
41
  processorId: string = "";
35
42
 
@@ -38,11 +45,15 @@ export class AutoProcessorConfig extends Ad4mModel {
38
45
  sourceScopeQuery: string = "";
39
46
 
40
47
  /** URI prefix for minted instances; omit for the per-processor default. */
41
- @Optional({ through: "ad4m://base_prefix", resolveLanguage: "literal" })
48
+ // No resolveLanguage — Rust SDNA declares none for this property, so under
49
+ // PR #874 both sides get the fast deterministic typed-literal path.
50
+ // (resolveLanguage: "literal" would ask the executor for a signed envelope
51
+ // that the Rust writer never produces for config metadata.)
52
+ @Optional({ through: "ad4m://base_prefix" })
42
53
  basePrefix?: string;
43
54
 
44
55
  /** Class URIs (SHACL targetClass) to materialise each pass. */
45
- @HasMany({ through: "ad4m://interpretation_class" })
56
+ @HasMany({ through: "ad4m://interpretation_class", datatype: "xsd:string" })
46
57
  interpretationClasses: string[] = [];
47
58
 
48
59
  /** Quiet-window (ms) after the last new item before a pass runs. */
@@ -50,7 +61,7 @@ export class AutoProcessorConfig extends Ad4mModel {
50
61
  debounceMs: string = "200";
51
62
 
52
63
  /** Minimum batch size before a pass runs (default 1). */
53
- @Optional({ through: "ad4m://batch_min", resolveLanguage: "literal" })
64
+ @Optional({ through: "ad4m://batch_min" })
54
65
  batchMin?: string;
55
66
 
56
67
  /** Maximum items per pass. */
@@ -58,7 +69,7 @@ export class AutoProcessorConfig extends Ad4mModel {
58
69
  batchMax: string = "32";
59
70
 
60
71
  /** Safety flush (ms) for a sub-`batchMin` batch; absent = wait indefinitely. */
61
- @Optional({ through: "ad4m://max_wait_ms", resolveLanguage: "literal" })
72
+ @Optional({ through: "ad4m://max_wait_ms" })
62
73
  maxWaitMs?: string;
63
74
 
64
75
  /** How long a won claim is authoritative before peers may re-claim (ms). */
@@ -66,12 +77,59 @@ export class AutoProcessorConfig extends Ad4mModel {
66
77
  claimTtlMs: string = "60000";
67
78
 
68
79
  /** How far back (ms) each pass looks; absent = unbounded. */
69
- @Optional({ through: "ad4m://source_window_ms", resolveLanguage: "literal" })
80
+ @Optional({ through: "ad4m://source_window_ms" })
70
81
  sourceWindowMs?: string;
71
82
 
72
83
  /** Serialised `DedupStrategy` JSON (absent = NormalizedString). */
73
- @Optional({ through: "ad4m://dedup_strategy", resolveLanguage: "literal" })
84
+ @Optional({ through: "ad4m://dedup_strategy" })
74
85
  dedupStrategy?: string;
86
+
87
+ /**
88
+ * Serialised `Scope` JSON (absent = whole-perspective dedup set).
89
+ * Constrains the existing-instance lookup to the subtree rooted at
90
+ * `Scope.id` linked via `Scope.predicate` — the SoA-tree "existing items
91
+ * live under THIS project node" pattern. Stored as an opaque JSON blob
92
+ * because SHACL properties carry no rich-object type-check; the Rust
93
+ * watcher parses it back into `Scope`.
94
+ */
95
+ @Optional({ through: "ad4m://existing_scope" })
96
+ existingScope?: string;
97
+
98
+ /**
99
+ * Serialised `Scope` JSON (absent = mint sites are unlinked). When set,
100
+ * every freshly created base URI gets an additional `Scope.id
101
+ * --Scope.predicate--> new-uri` link written into the perspective, so
102
+ * mints become first-class children of the target scope. Must be the
103
+ * `Raw` form of `Scope`; `Model` scopes carry no linking predicate.
104
+ */
105
+ @Optional({ through: "ad4m://mint_scope" })
106
+ mintScope?: string;
107
+
108
+ /**
109
+ * Tool-call budget for the interpretation-pass harness. Absent (or `"0"`)
110
+ * = the original single-shot LLM path — one prompt, one parse, no tools.
111
+ * `"N"` (positive integer) = engage the tool-calling harness and let the
112
+ * LLM issue up to N tool calls per pass (query/list/get/propose_create/
113
+ * propose_link_child) before being forced to answer. Stored as a decimal
114
+ * string because SHACL properties carry no numeric type; the Rust
115
+ * watcher parses it back to `u32`.
116
+ */
117
+ @Optional({ through: "ad4m://max_tool_calls" })
118
+ maxToolCalls?: string;
119
+
120
+ /**
121
+ * Enable full debug observability: persists the raw LLM prompt + response
122
+ * on the pass's `InterpretationRun` AND emits `LlmRequestSent` /
123
+ * `LlmResponseReceived` mid-pass events. `"true"` / `"false"` string.
124
+ */
125
+ @Optional({ through: "ad4m://emit_debug_events", resolveLanguage: "literal" })
126
+ emitDebugEvents?: string;
127
+
128
+ // No `@Flag` type discriminator (Nico 2026-08-19: "type flags are an
129
+ // anti-pattern for subject classes; match over all the properties
130
+ // instead"). Conformance is by the presence of `processorId` +
131
+ // `sourceScopeQuery` + `interpretationClasses` + `debounceMs` +
132
+ // `batchMax` + `claimTtlMs` — the Rust SDNA takes the same shape.
75
133
  }
76
134
 
77
135
  // ── InterpretationRun ───────────────────────────────────────────────────────
@@ -80,36 +138,48 @@ export class AutoProcessorConfig extends Ad4mModel {
80
138
 
81
139
  @Model({ name: "InterpretationRun" })
82
140
  export class InterpretationRun extends Ad4mModel {
83
- @Flag({ through: "ad4m://type", value: "ad4m://interpretation-run" })
84
- type: string = "ad4m://interpretation-run";
141
+ // No `@Flag` type discriminator — Rust SDNA drops `ad4m://type` too.
142
+ // Conformance is by `runId` (identity) — same pattern
143
+ // `InterpretationOverlay` already uses (`kind` is its discriminator).
85
144
 
86
145
  /** UUID for this run — the dedup key across run nodes. */
87
146
  @Property({ through: "ad4m://interp/run_id", required: true, identity: true })
88
147
  runId: string = "";
89
148
 
90
149
  /** LLM model id used for this run. */
91
- @Optional({ through: "ad4m://interp/model", resolveLanguage: "literal" })
150
+ @Optional({ through: "ad4m://interp/model" })
92
151
  model?: string;
93
152
 
94
153
  /** SHA-256 hex of the system prompt + few-shots at the time of the run. */
95
- @Optional({ through: "ad4m://interp/prompt_version", resolveLanguage: "literal" })
154
+ @Optional({ through: "ad4m://interp/prompt_version" })
96
155
  promptVersion?: string;
97
156
 
98
157
  /** RFC3339 timestamp when the run completed. */
99
- @Optional({ through: "ad4m://interp/ran_at", resolveLanguage: "literal" })
158
+ @Optional({ through: "ad4m://interp/ran_at" })
100
159
  ranAt?: string;
101
160
 
102
161
  /** URI of the AutoProcessorConfig node that triggered this run. */
103
- @Optional({ through: "ad4m://interp/processor", resolveLanguage: "literal" })
162
+ @Optional({ through: "ad4m://interp/processor" })
104
163
  processor?: string;
105
164
 
106
165
  /**
107
166
  * Source item IDs consumed by this pass.
108
167
  * Stored as multiple links with the same predicate; the processed-turn
109
- * cursor uses these to avoid re-interpreting a turn.
168
+ * cursor uses these to avoid re-interpreting a turn. Values are plain
169
+ * strings (turn hex), so the property opts into `sh:datatype`-gated
170
+ * literal decoding on hydration.
110
171
  */
111
- @HasMany({ through: "ad4m://interp/sources" })
172
+ @HasMany({ through: "ad4m://interp/sources", datatype: "xsd:string" })
112
173
  sources: string[] = [];
174
+
175
+ /** Raw LLM prompt this pass fed the model. Present only when the pass's
176
+ * AutoProcessor had `emitDebugEvents: true`. Absent by default. */
177
+ @Optional({ through: "ad4m://interp/debug_prompt", resolveLanguage: "literal" })
178
+ debugPrompt?: string;
179
+
180
+ /** Raw LLM response this pass received. Same rules as `debugPrompt`. */
181
+ @Optional({ through: "ad4m://interp/debug_response", resolveLanguage: "literal" })
182
+ debugResponse?: string;
113
183
  }
114
184
 
115
185
  // ── InterpretationOverlay ───────────────────────────────────────────────────
@@ -136,10 +206,10 @@ export class InterpretationOverlay extends Ad4mModel {
136
206
  * changes to an existing one (`"update"`). This is the discriminator link
137
207
  * that makes a node identifiable as an overlay.
138
208
  */
139
- @Property({ through: "ad4m://interp/kind", required: true, resolveLanguage: "literal" })
209
+ @Property({ through: "ad4m://interp/kind", required: true })
140
210
  kind: string = "";
141
211
 
142
212
  /** URI of the InterpretationRun that last wrote this overlay, if present. */
143
- @Optional({ through: "ad4m://interp/run", resolveLanguage: "literal" })
213
+ @Optional({ through: "ad4m://interp/run" })
144
214
  run?: string;
145
215
  }
@@ -188,12 +188,73 @@ describe('PerspectiveClient RPC operations', () => {
188
188
  const client = new PerspectiveClient('http://localhost:12000', 'token', false)
189
189
  await client.queryLinks('uuid-q', new LinkQuery({ source: 'src', predicate: 'pred', target: 'tgt' }))
190
190
 
191
- expect(mockCall).toHaveBeenCalledWith('perspective.queryLinks', expect.objectContaining({
192
- uuid: 'uuid-q',
193
- source: 'src',
194
- predicate: 'pred',
195
- target: 'tgt',
196
- }))
191
+ expect(mockCall).toHaveBeenCalledWith(
192
+ 'perspective.queryLinks',
193
+ expect.objectContaining({
194
+ uuid: 'uuid-q',
195
+ source: 'src',
196
+ predicate: 'pred',
197
+ target: 'tgt',
198
+ }),
199
+ undefined,
200
+ )
201
+ })
202
+
203
+ // ── CallOptions forwarding (AbortSignal plumbing) ──────────────────
204
+ //
205
+ // These tests prove the new `options?` parameter on the long-running
206
+ // query methods reaches `ApiClient.call` as the third argument. The
207
+ // wire-protocol behaviour (request.cancel + AbortError rejection) is
208
+ // covered separately in apiClient.test.ts; here we just verify the
209
+ // signal propagates through the SDK layer instead of being silently
210
+ // dropped.
211
+
212
+ it('querySparql forwards options to apiClient.call', async () => {
213
+ mockCall.mockResolvedValue(JSON.stringify([]))
214
+ const client = new PerspectiveClient('http://localhost:12000', 'token', false)
215
+ const controller = new AbortController()
216
+ await client.querySparql('uuid-q', 'SELECT * WHERE { ?s ?p ?o }', { signal: controller.signal })
217
+ expect(mockCall).toHaveBeenCalledWith(
218
+ 'perspective.querySparql',
219
+ expect.objectContaining({ uuid: 'uuid-q', query: 'SELECT * WHERE { ?s ?p ?o }' }),
220
+ { signal: controller.signal },
221
+ )
222
+ })
223
+
224
+ it('modelQuery forwards options to apiClient.call', async () => {
225
+ mockCall.mockResolvedValue(JSON.stringify({ instances: [], totalCount: 0 }))
226
+ const client = new PerspectiveClient('http://localhost:12000', 'token', false)
227
+ const controller = new AbortController()
228
+ await client.modelQuery('uuid-q', 'Recipe', '{}', { signal: controller.signal })
229
+ expect(mockCall).toHaveBeenCalledWith(
230
+ 'perspective.modelQuery',
231
+ expect.objectContaining({ uuid: 'uuid-q', class_name: 'Recipe' }),
232
+ { signal: controller.signal },
233
+ )
234
+ })
235
+
236
+ it('queryLinks forwards options to apiClient.call', async () => {
237
+ mockCall.mockResolvedValue([])
238
+ const client = new PerspectiveClient('http://localhost:12000', 'token', false)
239
+ const controller = new AbortController()
240
+ await client.queryLinks('uuid-q', new LinkQuery({ source: 'src' }), { signal: controller.signal })
241
+ expect(mockCall).toHaveBeenCalledWith(
242
+ 'perspective.queryLinks',
243
+ expect.objectContaining({ uuid: 'uuid-q', source: 'src' }),
244
+ { signal: controller.signal },
245
+ )
246
+ })
247
+
248
+ it('queryProlog forwards options to apiClient.call', async () => {
249
+ mockCall.mockResolvedValue(JSON.stringify([]))
250
+ const client = new PerspectiveClient('http://localhost:12000', 'token', false)
251
+ const controller = new AbortController()
252
+ await client.queryProlog('uuid-q', 'foo(X).', { signal: controller.signal })
253
+ expect(mockCall).toHaveBeenCalledWith(
254
+ 'perspective.queryProlog',
255
+ expect.objectContaining({ uuid: 'uuid-q', query: 'foo(X).' }),
256
+ { signal: controller.signal },
257
+ )
197
258
  })
198
259
  })
199
260
 
@@ -1,4 +1,4 @@
1
- import { ApiClient, RpcError } from "../apiClient";
1
+ import { ApiClient, CallOptions, RpcError } 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, InterpretationOverlayInfo } from "./AutoProcessor";
14
+ import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
15
15
 
16
16
  export type PerspectiveHandleCallback = (perspective: PerspectiveHandle) => null
17
17
  export type UuidCallback = (uuid: string) => null
@@ -102,7 +102,7 @@ export class PerspectiveClient {
102
102
  return this.#apiClient.call<string|null>('perspective.publishSnapshot', { uuid })
103
103
  }
104
104
 
105
- async queryLinks(uuid: string, query: LinkQuery): Promise<LinkExpression[]> {
105
+ async queryLinks(uuid: string, query: LinkQuery, options?: CallOptions): Promise<LinkExpression[]> {
106
106
  const params: Record<string, unknown> = { uuid }
107
107
  if (query.source) params.source = query.source
108
108
  if (query.predicate) params.predicate = query.predicate
@@ -110,16 +110,16 @@ export class PerspectiveClient {
110
110
  if (query.fromDate) params.fromDate = query.fromDate instanceof Date ? query.fromDate.toISOString() : String(query.fromDate)
111
111
  if (query.untilDate) params.untilDate = query.untilDate instanceof Date ? query.untilDate.toISOString() : String(query.untilDate)
112
112
  if (query.limit !== undefined) params.limit = query.limit
113
- return this.#apiClient.call<LinkExpression[]>('perspective.queryLinks', params)
113
+ return this.#apiClient.call<LinkExpression[]>('perspective.queryLinks', params, options)
114
114
  }
115
115
 
116
- async queryProlog(uuid: string, query: string): Promise<unknown> {
117
- const result = await this.#apiClient.call<string>('perspective.queryProlog', { uuid, query })
116
+ async queryProlog(uuid: string, query: string, options?: CallOptions): Promise<unknown> {
117
+ const result = await this.#apiClient.call<string>('perspective.queryProlog', { uuid, query }, options)
118
118
  return JSON.parse(result)
119
119
  }
120
120
 
121
- async querySparql<T = any>(uuid: string, query: string): Promise<T> {
122
- const result = await this.#apiClient.call<string>('perspective.querySparql', { uuid, engine: 'sparql', query })
121
+ async querySparql<T = any>(uuid: string, query: string, options?: CallOptions): Promise<T> {
122
+ const result = await this.#apiClient.call<string>('perspective.querySparql', { uuid, engine: 'sparql', query }, options)
123
123
  return JSON.parse(result) as T
124
124
  }
125
125
 
@@ -178,13 +178,19 @@ export class PerspectiveClient {
178
178
  )
179
179
  }
180
180
 
181
- async modelQuery(uuid: string, className: string, queryJson: string): Promise<any> {
181
+ async modelQuery(uuid: string, className: string, queryJson: string, options?: CallOptions): Promise<any> {
182
182
  const resultJson = await this.#apiClient.call<string>(
183
- 'perspective.modelQuery', { uuid, class_name: className, query_json: queryJson }
183
+ 'perspective.modelQuery', { uuid, class_name: className, query_json: queryJson }, options
184
184
  )
185
185
  return JSON.parse(resultJson)
186
186
  }
187
187
 
188
+ async subjectClassesOf(uuid: string, uris: string[]): Promise<Record<string, string[]>> {
189
+ return await this.#apiClient.call<Record<string, string[]>>(
190
+ 'perspective.subjectClassesOf', { uuid, uris }
191
+ )
192
+ }
193
+
188
194
  async evaluateGetters(
189
195
  uuid: string,
190
196
  className: string,
@@ -261,12 +267,87 @@ export class PerspectiveClient {
261
267
  * retries on parse failure), so it can legitimately take minutes on slower
262
268
  * or CPU-only models. We raise the default 30s RPC timeout here to 20 min
263
269
  * (matches the CI `--timeout 1200000` for the interpretation tests).
270
+ *
271
+ * `existingScope` and `mintScope` match the AutoProcessor semantics:
272
+ * `existingScope` constrains the dedup lookup to instances under a
273
+ * subtree; `mintScope` links every FRESHLY-created base as a child of
274
+ * `mintScope.id` via its predicate (upserts of pre-existing instances
275
+ * are NOT re-parented — same rule as the watcher).
264
276
  */
265
- async runInterpretation(uuid: string, transcript: TranscriptTurn[], basePrefix: string, classes?: string[]): Promise<string[]> {
277
+ async runInterpretation(
278
+ uuid: string,
279
+ transcript: TranscriptTurn[],
280
+ basePrefix: string,
281
+ classes?: string[],
282
+ existingScope?: RawScope,
283
+ mintScope?: RawScope,
284
+ observe?: RunInterpretationObserveOptions,
285
+ ): Promise<string[]> {
286
+ const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000
287
+ return this.#apiClient.call<string[]>(
288
+ 'perspective.runInterpretation',
289
+ {
290
+ uuid, transcript, basePrefix, classes, existingScope, mintScope,
291
+ // Spread rather than always-present, so a client talking to a pre-#903
292
+ // executor sends exactly the params it sent before. `serde` would ignore
293
+ // the extra keys anyway; keeping the wire identical means a bug report
294
+ // from an older node cannot be about these.
295
+ ...(observe ? {
296
+ observationId: observe.observationId,
297
+ emitDebugEvents: observe.emitDebugEvents ?? false,
298
+ } : {}),
299
+ },
300
+ { timeoutMs: RUN_INTERPRETATION_TIMEOUT_MS },
301
+ )
302
+ }
303
+
304
+ /**
305
+ * Tool-calling counterpart to {@link runInterpretation}. The LLM sees a
306
+ * live per-class tool surface (`{Class}_query`, `{Class}_propose_create`,
307
+ * `{Class}_propose_link_child`, …) and drives the extraction via tool
308
+ * calls; buffered proposals drain through the same overlay gate the
309
+ * single-shot path uses.
310
+ *
311
+ * `maxToolCalls` bounds the loop and MUST be > 0 — zero would collapse
312
+ * the harness to a no-op final-answer step; use {@link runInterpretation}
313
+ * for the classic single-shot path.
314
+ *
315
+ * Same 20-minute RPC timeout as the single-shot path — an LLM loop
316
+ * that calls several tools can legitimately take longer than one plain
317
+ * generation.
318
+ */
319
+ async runInterpretationWithHarness(
320
+ uuid: string,
321
+ transcript: TranscriptTurn[],
322
+ basePrefix: string,
323
+ maxToolCalls: number,
324
+ classes?: string[],
325
+ modelOverride?: string,
326
+ existingScope?: RawScope,
327
+ // Optional live-debug event surface — same shape/semantics as the
328
+ // single-shot `runInterpretation`. `observationId` names the
329
+ // `processor_id` + `batch_key` on emitted `ToolCall` / `ToolResult`
330
+ // events so a subscribed UI can correlate them to this pass.
331
+ // `emitDebugEvents` is a dead-letter without an observationId
332
+ // (nothing to key against); the server gates on both.
333
+ observationId?: string,
334
+ emitDebugEvents?: boolean,
335
+ ): Promise<string[]> {
266
336
  const RUN_INTERPRETATION_TIMEOUT_MS = 20 * 60 * 1000
267
337
  return this.#apiClient.call<string[]>(
268
- 'perspective.runInterpretation', { uuid, transcript, basePrefix, classes },
269
- RUN_INTERPRETATION_TIMEOUT_MS,
338
+ 'perspective.runInterpretationWithHarness',
339
+ {
340
+ uuid,
341
+ transcript,
342
+ basePrefix,
343
+ maxToolCalls,
344
+ classes,
345
+ modelOverride,
346
+ existingScope,
347
+ observationId,
348
+ emitDebugEvents,
349
+ },
350
+ { timeoutMs: RUN_INTERPRETATION_TIMEOUT_MS },
270
351
  )
271
352
  }
272
353
 
@@ -284,6 +365,13 @@ export class PerspectiveClient {
284
365
  )
285
366
  }
286
367
 
368
+ /** Delete an auto-processor's config. `false` when there was none to delete. */
369
+ async removeAutoProcessor(uuid: string, processorId: string): Promise<boolean> {
370
+ return this.#apiClient.call<boolean>(
371
+ 'perspective.removeAutoProcessor', { uuid, processorId },
372
+ )
373
+ }
374
+
287
375
  /** Pending interpretation overlays (LLM suggestions awaiting human accept/reject). */
288
376
  async interpretationOverlays(uuid: string): Promise<InterpretationOverlayInfo[]> {
289
377
  return this.#apiClient.call<InterpretationOverlayInfo[]>(
@@ -311,6 +399,11 @@ export class PerspectiveClient {
311
399
  * Subscribe to auto-processor step signals. `cb` fires for every
312
400
  * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
313
401
  * Processed), letting a UI show progress and await the next batch.
402
+ *
403
+ * Registered on the per-uuid `#linkUnsubscribers` map so
404
+ * `PerspectiveProxy.dispose()` → `removeAllListeners(uuid)` cleans the
405
+ * subscription up; using the global `#unsubscribers` array would leak
406
+ * callbacks across repeated view lifecycles (CodeRabbit #881 review).
314
407
  */
315
408
  async addAutoProcessorEventListener(uuid: String, cb: (event: AutoProcessorEvent) => void): Promise<void> {
316
409
  const unsub = this.#apiClient.subscribe(
@@ -320,7 +413,34 @@ export class PerspectiveClient {
320
413
  }
321
414
  }
322
415
  )
323
- this.#unsubscribers.push(unsub)
416
+ let existing = this.#linkUnsubscribers.get(uuid as string) || []
417
+ existing.push(unsub)
418
+ this.#linkUnsubscribers.set(uuid as string, existing)
419
+ await this.#apiClient.waitForSubscription()
420
+ }
421
+
422
+ /**
423
+ * Subscribe to neighbourhood-state events on a perspective. `cb` fires
424
+ * when THIS executor claims / finishes / abandons a batch for any
425
+ * processor on `uuid` — perspective-scoped observability so a UI can
426
+ * render "someone is auto-processing this" without receiving the batch
427
+ * payload or LLM I/O. Registered on the per-uuid `#linkUnsubscribers`
428
+ * map so `PerspectiveProxy.dispose()` sweeps it up.
429
+ */
430
+ async addAutoProcessorNeighbourhoodStateListener(
431
+ uuid: String,
432
+ cb: (event: AutoProcessorNeighbourhoodStateEvent) => void,
433
+ ): Promise<void> {
434
+ const unsub = this.#apiClient.subscribe(
435
+ (data) => {
436
+ if (data.type === 'auto-processor-neighbourhood-state' && data.perspectiveUuid === uuid) {
437
+ cb(data as unknown as AutoProcessorNeighbourhoodStateEvent)
438
+ }
439
+ }
440
+ )
441
+ let existing = this.#linkUnsubscribers.get(uuid as string) || []
442
+ existing.push(unsub)
443
+ this.#linkUnsubscribers.set(uuid as string, existing)
324
444
  await this.#apiClient.waitForSubscription()
325
445
  }
326
446
 
@@ -376,6 +496,56 @@ export class PerspectiveClient {
376
496
  )
377
497
  }
378
498
 
499
+ // ── SHACL resolution (server-side) ─────────────────────────────────────────
500
+ // These methods delegate shape resolution to the executor, which reads links
501
+ // from its local store in-process. Each call replaces the multi-round-trip
502
+ // `queryLinks` sequences the old PerspectiveProxy methods performed.
503
+
504
+ /** List the names of every SHACL shape stored in a perspective (one RPC call). */
505
+ async getShaclNames(uuid: string): Promise<string[]> {
506
+ return this.#apiClient.call<string[]>('perspective.getShaclNames', { uuid })
507
+ }
508
+
509
+ /**
510
+ * Resolve a shape's `sh:targetClass` by name (one RPC call).
511
+ *
512
+ * Returns `undefined` when the shape (or its `sh://targetClass` edge) is
513
+ * absent — unified with `PerspectiveProxy.getShaclTargetClass` so callers
514
+ * see a single "not found" representation across both layers. The
515
+ * executor wire format is still `null` (see `perspective.getShaclTargetClass`
516
+ * in `perspectives_ws.rs`); this method maps that at the boundary rather
517
+ * than pushing the null one layer further up. PR #935 review r3897752023.
518
+ */
519
+ async getShaclTargetClass(uuid: string, name: string): Promise<string | undefined> {
520
+ const result = await this.#apiClient.call<string | null>(
521
+ 'perspective.getShaclTargetClass',
522
+ { uuid, name },
523
+ )
524
+ return result ?? undefined
525
+ }
526
+
527
+ /**
528
+ * Retrieve a single SHACL shape's link triples by name (one RPC call).
529
+ * Returns `{shapeUri, links}` for reconstruction via `SHACLShape.fromLinks()`,
530
+ * or `null` if no shape with that name exists.
531
+ */
532
+ async getShacl(uuid: string, name: string): Promise<{ shapeUri: string; links: Array<{source: string; predicate: string; target: string}> } | null> {
533
+ return this.#apiClient.call<{ shapeUri: string; links: Array<{source: string; predicate: string; target: string}> } | null>(
534
+ 'perspective.getShacl', { uuid, name }
535
+ )
536
+ }
537
+
538
+ /**
539
+ * Retrieve all SHACL shapes in one call. Returns an array of
540
+ * `{name, shapeUri, links}` — one entry per shape (one RPC call).
541
+ */
542
+ async getAllShacl(uuid: string): Promise<Array<{ name: string; shapeUri: string; links: Array<{source: string; predicate: string; target: string}> }>> {
543
+ return this.#apiClient.call<Array<{ name: string; shapeUri: string; links: Array<{source: string; predicate: string; target: string}> }>>(
544
+ 'perspective.getAllShacl', { uuid }
545
+ )
546
+ }
547
+
548
+
379
549
  // ExpressionClient functions, needed for Subjects:
380
550
  async getExpression(expressionURI: string): Promise<ExpressionRendered> {
381
551
  return await this.#expressionClient!.get(expressionURI)
@@ -520,4 +690,10 @@ export class PerspectiveClient {
520
690
  'perspective.commitBatch', { uuid, batchId }
521
691
  )
522
692
  }
693
+
694
+ /** Register a callback that fires after a successful WebSocket reconnect.
695
+ * Passes through to ApiClient.onReconnect(). Returns an unsubscribe function. */
696
+ onReconnect(callback: () => void): () => void {
697
+ return this.#apiClient.onReconnect(callback)
698
+ }
523
699
  }