@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
@@ -36,9 +36,30 @@ export declare function parseSparqlCount(result: CountBinding[] | undefined | nu
36
36
  /**
37
37
  * Decode a `Literal`-encoded SPARQL binding back to a plain string.
38
38
  *
39
- * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
40
- * input. Falls through to the raw value if decoding fails (defensive — the
41
- * binding may already be a plain string for unwrapped properties).
39
+ * Returns `''` for `undefined`/empty input. Falls through to the raw value
40
+ * if decoding fails — bindings against properties resolved through a custom
41
+ * language are already raw URIs and should pass through unchanged.
42
+ *
43
+ * Signed-envelope literals
44
+ * ------------------------
45
+ * Properties declared with `resolveLanguage: 'literal'` are written through
46
+ * the built-in `literal` language, which wraps the value in a signed
47
+ * expression envelope (`{ author, timestamp, data, proof }`) and encodes
48
+ * the whole envelope as a `literal:json:` URL — see
49
+ * `rust-executor/src/languages/mod.rs::expression_create` (literal branch).
50
+ * On read, `parseLit` unwraps `.data` from that envelope so callers get the
51
+ * original scalar value instead of the envelope JSON.
52
+ *
53
+ * The Channel V refactor moved most scalar properties to deterministic
54
+ * typed XSD literals which no longer round-trip through this envelope — for
55
+ * those properties the SPARQL binding is already the lexical form and this
56
+ * helper decodes to the primitive. Signed-envelope literals still exist
57
+ * for any property that opts back into `resolveLanguage: 'literal'` (e.g.
58
+ * per-message provenance for chat bodies), which is why the `.data` unwrap
59
+ * is preserved here.
60
+ *
61
+ * Non-envelope JSON objects (`literal:json:` payloads that are not signed
62
+ * envelopes) are JSON-stringified for display.
42
63
  */
43
64
  export declare function parseLit(val: string | undefined | null): string;
44
65
  /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
@@ -31,23 +31,74 @@ export function parseSparqlCount(result) {
31
31
  /**
32
32
  * Decode a `Literal`-encoded SPARQL binding back to a plain string.
33
33
  *
34
- * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
35
- * input. Falls through to the raw value if decoding fails (defensive — the
36
- * binding may already be a plain string for unwrapped properties).
34
+ * Returns `''` for `undefined`/empty input. Falls through to the raw value
35
+ * if decoding fails — bindings against properties resolved through a custom
36
+ * language are already raw URIs and should pass through unchanged.
37
+ *
38
+ * Signed-envelope literals
39
+ * ------------------------
40
+ * Properties declared with `resolveLanguage: 'literal'` are written through
41
+ * the built-in `literal` language, which wraps the value in a signed
42
+ * expression envelope (`{ author, timestamp, data, proof }`) and encodes
43
+ * the whole envelope as a `literal:json:` URL — see
44
+ * `rust-executor/src/languages/mod.rs::expression_create` (literal branch).
45
+ * On read, `parseLit` unwraps `.data` from that envelope so callers get the
46
+ * original scalar value instead of the envelope JSON.
47
+ *
48
+ * The Channel V refactor moved most scalar properties to deterministic
49
+ * typed XSD literals which no longer round-trip through this envelope — for
50
+ * those properties the SPARQL binding is already the lexical form and this
51
+ * helper decodes to the primitive. Signed-envelope literals still exist
52
+ * for any property that opts back into `resolveLanguage: 'literal'` (e.g.
53
+ * per-message provenance for chat bodies), which is why the `.data` unwrap
54
+ * is preserved here.
55
+ *
56
+ * Non-envelope JSON objects (`literal:json:` payloads that are not signed
57
+ * envelopes) are JSON-stringified for display.
37
58
  */
38
59
  export function parseLit(val) {
39
60
  if (val === undefined || val === null || val === '')
40
61
  return '';
62
+ // Fast-path 1: `literal:*` URLs from properties written through the built-in
63
+ // `literal` language. On Channel V typed-XSD-literal properties, these
64
+ // decode straight to a primitive; on `resolveLanguage: 'literal'` properties
65
+ // (per-message provenance in chat/synergy) they decode to a signed-envelope
66
+ // object we unwrap via `.data`.
41
67
  try {
42
68
  const result = Literal.fromUrl(val).get();
43
- if (result && typeof result === 'object') {
44
- return result.data ?? JSON.stringify(result);
69
+ if (typeof result === 'object' && result !== null) {
70
+ const data = result.data;
71
+ if (typeof data === 'string')
72
+ return data;
73
+ return JSON.stringify(result);
45
74
  }
46
75
  return String(result);
47
76
  }
48
77
  catch {
49
- return val;
78
+ // fall through to plain-JSON envelope detection
79
+ }
80
+ // Fast-path 2: envelope stored/returned as a bare JSON string rather than a
81
+ // `literal:json:*` URL. Depending on the storage backend and query path,
82
+ // SPARQL bindings for `resolveLanguage: 'literal'` properties can surface
83
+ // the envelope object directly as its JSON serialisation (Oxigraph typed
84
+ // xsd:string of the JSON, or a Channel V pass-through) instead of the URL
85
+ // form. Detect that shape by parsing the string and unwrapping `.data`
86
+ // when it looks like a signed envelope; anything else passes through
87
+ // unchanged so plain text (e.g. "just a string") is not corrupted.
88
+ if (val.length >= 2 && val.charCodeAt(0) === 0x7b /* '{' */) {
89
+ try {
90
+ const parsed = JSON.parse(val);
91
+ if (parsed && typeof parsed === 'object') {
92
+ const data = parsed.data;
93
+ if (typeof data === 'string')
94
+ return data;
95
+ }
96
+ }
97
+ catch {
98
+ // not JSON — fall through and return the raw value
99
+ }
50
100
  }
101
+ return val;
51
102
  }
52
103
  /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
53
104
  export function parseLitNumber(val) {
@@ -13,6 +13,134 @@ export interface LinkPattern {
13
13
  /** Required target value to match */
14
14
  target: string;
15
15
  }
16
+ /**
17
+ * Per-property condition for a `ModelQuery`. String / number / boolean
18
+ * shorthands compile to an equality match; the object forms are the full
19
+ * shape a `ModelQuery` engine consumer will evaluate against a class
20
+ * instance's decoded property value.
21
+ *
22
+ * Only the shorthand + `equals` / `in` / `exists` / `matches` operators are
23
+ * declared in v1 (see design doc §4.1). More operators can land as
24
+ * additional variants without a schema break.
25
+ */
26
+ export type PropertyCondition = string | number | boolean | {
27
+ equals: unknown;
28
+ } | {
29
+ in: unknown[];
30
+ } | {
31
+ exists: true;
32
+ } | {
33
+ matches: string;
34
+ };
35
+ /**
36
+ * A model-level query — the shape a flow's `requires` guard evaluates
37
+ * against the perspective's current class-instance graph. Deliberately
38
+ * higher-level than raw links so guards talk about subject classes, not
39
+ * the underlying triples.
40
+ *
41
+ * See design doc §3 principle 2 ("Guards talk about models, not raw graph")
42
+ * and §4.1 for the full field spec. Template variables allowed inside
43
+ * `where` string values: `$flow.base`, `$flow.uri` (alias:
44
+ * `$flow.instance`), `$did` — the engine substitutes at evaluation time.
45
+ */
46
+ export interface ModelQuery {
47
+ /** Subject-class URI to search for. */
48
+ className: string;
49
+ /**
50
+ * Per-property conditions (all must match — AND semantics inside one
51
+ * ModelQuery, same as AND semantics across an array of ModelQueries).
52
+ */
53
+ where?: {
54
+ [prop: string]: PropertyCondition | string;
55
+ };
56
+ /**
57
+ * Cardinality constraint on matching instances. Default `{ min: 1 }` —
58
+ * at least one match required to satisfy the guard.
59
+ */
60
+ count?: {
61
+ min?: number;
62
+ max?: number;
63
+ };
64
+ /**
65
+ * Scope the query to instances linked from a flow anchor. The anchor
66
+ * (base subject or flow instance URI) is the **source** of the link and
67
+ * the matched item is the **target**: `linkedTo: "base"` finds items
68
+ * where the base subject links TO them via the default predicate
69
+ * `ad4m://has_child`.
70
+ *
71
+ * `"base"` / `"flow"` use `ad4m://has_child`; the object form
72
+ * `{ via, to }` names a custom predicate (e.g.
73
+ * `{ via: "ns://about", to: "flow" }`).
74
+ *
75
+ * For the reverse direction (matched instance → anchor), use
76
+ * `where: { about: "$flow.base" }` instead — `linkedTo` cannot
77
+ * express that direction.
78
+ */
79
+ linkedTo?: "flow" | "base" | {
80
+ via: string;
81
+ to: "flow" | "base";
82
+ };
83
+ /**
84
+ * When this query is used as a `ConsensusRule.fromRole`, names the
85
+ * property on the matched instance that carries a DID. Design doc §7.2
86
+ * Shape 1 (instance-carries-DID): engine runs the query, then extracts
87
+ * `didProperty` from each result to build the eligible-DID set.
88
+ *
89
+ * Shape 2 (instance-is-per-DID, using `$did` templating in `where`)
90
+ * omits `didProperty` — the engine iterates candidate DIDs and treats
91
+ * a non-empty result set as "this DID matches."
92
+ *
93
+ * Ignored when the query is used as a state guard (`requires`) or
94
+ * background `context`.
95
+ */
96
+ didProperty?: string;
97
+ /**
98
+ * OR-compose a role expression across multiple ModelQueries. Semantics:
99
+ * a DID counts if it appears in the result of ANY branch (design §7.3
100
+ * multi-role hybrid example — "either reviewer OR admin"). Branches
101
+ * can carry their own `didProperty` / `where`, but NOT `linkedTo`
102
+ * (which must be on the outer query — `linkedTo` on a branch is
103
+ * rejected at translation time).
104
+ *
105
+ * Every branch must use the same `className` as the outer query and
106
+ * cannot declare its own `count` — the outer query's class and
107
+ * cardinality apply to the combined result set.
108
+ *
109
+ * A ModelQuery with a non-empty `or` array acts as a composition node;
110
+ * its own `className` / `where` etc. still count as an additional
111
+ * branch (union with the array). Empty or unset = no composition.
112
+ *
113
+ * Intentionally scoped to `or` for v1 — `and` / `not` fall out of the
114
+ * same mechanism and can land later without a schema break (design
115
+ * §7.4). Ignored when the query is used as a state guard or context.
116
+ */
117
+ or?: ModelQuery[];
118
+ }
119
+ /**
120
+ * Consensus rule for a flow-state transition (or a top-level zero-state
121
+ * flow's completion). Distinct DID counting with optional role
122
+ * restriction.
123
+ *
124
+ * Design doc §7:
125
+ * - `{ n: 1 }` — any agent's proposal advances (default).
126
+ * - `{ n: 2 }` — two distinct agents must agree.
127
+ * - `{ n, fromRole }` — only agents matching the role query count.
128
+ *
129
+ * `fromRole` reuses `ModelQuery` (design §7.2) so role definitions live
130
+ * entirely in the ontology — communities can invent roles like
131
+ * "Reviewer" / "Guardian" without any code change.
132
+ */
133
+ export interface ConsensusRule {
134
+ /** Required count of distinct qualifying DIDs. */
135
+ n: number;
136
+ /**
137
+ * Optional role restriction. When set, only DIDs returned by the role
138
+ * query are counted. Two evaluation shapes (design §7.2):
139
+ * Shape 1 — `didProperty` present: run once, extract DIDs from matches.
140
+ * Shape 2 — `$did` templated in `where`: run per candidate.
141
+ */
142
+ fromRole?: ModelQuery;
143
+ }
16
144
  /**
17
145
  * Flow State definition
18
146
  * Represents a single state in the flow state machine
@@ -22,8 +150,54 @@ export interface FlowState {
22
150
  name: string;
23
151
  /** Numeric state value for ordering (e.g., 0, 0.5, 1) */
24
152
  value: number;
25
- /** Link pattern that indicates this state */
26
- stateCheck: LinkPattern;
153
+ /**
154
+ * Natural-language description of what puts a flow instance IN this state.
155
+ * Used by AI-driven state suggestion (`suggestFlowState`) — the same
156
+ * pattern subject classes use for `interpretationHint`. When set, the LLM
157
+ * reads it alongside conversation content to suggest transitions.
158
+ *
159
+ * Example (Deliberation Flow, "Tension" state):
160
+ * "Participants have voiced opposing views or objections — there is a
161
+ * clear disagreement or unresolved conflict on the table."
162
+ */
163
+ interpretationHint?: string;
164
+ /**
165
+ * Model-level guard: the state is satisfied when every ModelQuery in
166
+ * the array returns at least one match on committed graph state
167
+ * (overlays do NOT count as evidence — design §3 principle 5).
168
+ *
169
+ * Array semantics: AND — every entry must match. Empty / unset =
170
+ * no model-level guard.
171
+ *
172
+ * Design doc §4.1: "an array of queries, ALL must match; each query's
173
+ * matches become evidence."
174
+ */
175
+ requires?: ModelQuery[];
176
+ /**
177
+ * Optional English hint for a targeted LLM confirmation before the
178
+ * engine declares the state entered. Distinct from
179
+ * `interpretationHint`, which frames the state semantically for the
180
+ * up-front extraction pass — `semanticCheck` is the "am I still
181
+ * confident?" pass the engine runs after `requires` matches, for
182
+ * states where structural presence isn't enough (e.g. tension
183
+ * resolution).
184
+ *
185
+ * Design doc §5 covers the LLM confirmation pass shape. Unset = no
186
+ * confirmation, `requires` matches directly imply state entered.
187
+ */
188
+ semanticCheck?: string;
189
+ /**
190
+ * Per-state consensus rule override. When present, transitions INTO
191
+ * this state require the specified number of distinct qualifying DIDs
192
+ * (see `ConsensusRule`). Overrides the flow-level `consensusRule` if
193
+ * both are set; when neither is set, the runtime engine's default of
194
+ * `{ n: 1 }` applies (any single agent's action fires the transition).
195
+ *
196
+ * Design doc §4.1 (v3) — per-state override enables mixed-consensus
197
+ * flows where e.g. "Perspective" states need only one voice but the
198
+ * "Resolution" state requires a quorum.
199
+ */
200
+ consensusRule?: ConsensusRule;
27
201
  }
28
202
  /**
29
203
  * Flow Transition definition
@@ -39,65 +213,40 @@ export interface FlowTransition {
39
213
  /** Actions to execute for this transition */
40
214
  actions: AD4MAction[];
41
215
  }
42
- /**
43
- * Flowable condition - determines which expressions can enter this flow
44
- * "any" means all expressions can start this flow
45
- * Otherwise, a link pattern to check
46
- */
47
- export type FlowableCondition = "any" | LinkPattern;
48
216
  /**
49
217
  * SHACL Flow - represents a state machine for AD4M expressions
50
218
  *
51
219
  * Flows define:
52
- * - Which expressions can enter the flow (flowable condition)
53
- * - What states exist and how to detect them (via link patterns)
54
- * - How to transition between states (via actions)
220
+ * - Which expressions can enter the flow (via `inputTypes`)
221
+ * - What states exist and their per-state guards (via `requires`)
222
+ * - How to transition between states (via transitions + consensus rules)
223
+ *
224
+ * State lives on the on-graph `FlowInstanceRecord.currentState` and is
225
+ * read/written through the `FlowInstance` wrapper class
226
+ * ({@link FlowInstance.start} / {@link FlowInstance.findAll}) — see design
227
+ * doc §4.3/§5.
55
228
  *
56
229
  * @example
57
230
  * ```typescript
58
231
  * const todoFlow = new SHACLFlow('todo://TODO', 'todo://');
59
232
  *
60
233
  * // Any expression can become a TODO
61
- * todoFlow.flowable = 'any';
234
+ * todoFlow.inputTypes = ['any'];
62
235
  *
63
- * // Define states
64
- * todoFlow.addState({
65
- * name: 'ready',
66
- * value: 0,
67
- * stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
68
- * });
69
- * todoFlow.addState({
70
- * name: 'doing',
71
- * value: 0.5,
72
- * stateCheck: { predicate: 'todo://state', target: 'todo://doing' }
73
- * });
74
- * todoFlow.addState({
75
- * name: 'done',
76
- * value: 1,
77
- * stateCheck: { predicate: 'todo://state', target: 'todo://done' }
78
- * });
236
+ * todoFlow.addState({ name: 'ready', value: 0 });
237
+ * todoFlow.addState({ name: 'doing', value: 0.5 });
238
+ * todoFlow.addState({ name: 'done', value: 1 });
79
239
  *
80
- * // Define start action
81
- * todoFlow.startAction = [{
82
- * action: 'addLink',
83
- * source: 'this',
84
- * predicate: 'todo://state',
85
- * target: 'todo://ready'
86
- * }];
87
- *
88
- * // Define transitions
89
240
  * todoFlow.addTransition({
90
241
  * actionName: 'Start',
91
242
  * fromState: 'ready',
92
243
  * toState: 'doing',
93
- * actions: [
94
- * { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://doing' },
95
- * { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
96
- * ]
244
+ * actions: [],
97
245
  * });
98
246
  *
99
- * // Store in perspective
247
+ * // Register on the perspective and mint an instance on a subject.
100
248
  * await perspective.addFlow('TODO', todoFlow);
249
+ * const instance = await FlowInstance.start(perspective, 'TODO', 'expr://123');
101
250
  * ```
102
251
  */
103
252
  export declare class SHACLFlow {
@@ -105,11 +254,88 @@ export declare class SHACLFlow {
105
254
  name: string;
106
255
  /** Namespace for generated URIs */
107
256
  namespace: string;
108
- /** Condition for which expressions can start this flow */
109
- flowable: FlowableCondition;
110
- /** Actions to execute when starting the flow */
111
- startAction: AD4MAction[];
112
- /** States in this flow */
257
+ /**
258
+ * Top-level natural-language description of what the flow is about — used
259
+ * by AI-driven state suggestion (`suggestFlowState`) to frame the state
260
+ * hints. Optional; states' own `interpretationHint`s are what actually
261
+ * discriminate. Example (Deliberation Flow):
262
+ * "Tracks a group deliberation from an initial proposal to a shared
263
+ * understanding — through voicing perspectives, surfacing tension, and
264
+ * finding overlap."
265
+ */
266
+ interpretationHint?: string;
267
+ /**
268
+ * Subject-class URIs the flow accepts as its base expression.
269
+ *
270
+ * Design doc §4.1: a flow's *typed input*. When an
271
+ * expression whose class matches any URI in this array enters scope,
272
+ * the flow-spawn engine considers it a candidate base. Superseded
273
+ * the older link-level `flowable: LinkPattern` primitive — model-level
274
+ * matching by subject class instead of link matching. Empty array =
275
+ * flow declares no typed input. The `"any"` sentinel is accepted as
276
+ * a wildcard for tests and legacy flows.
277
+ */
278
+ inputTypes: string[];
279
+ /**
280
+ * Subject-class URIs the flow must produce (linked to the base) for a
281
+ * run to count as complete.
282
+ *
283
+ * Design doc §4.1: a flow's *typed output*. Two jobs:
284
+ * (a) documentation for stateful flows — records what a completed run
285
+ * leaves in the graph; (b) **terminal condition** for zero-state flows —
286
+ * a flow with no `FlowState`s completes when at least one instance of
287
+ * each `outputTypes` entry exists in scope and is linked to the base,
288
+ * and `consensusRule` fires. This is what makes "Like" a first-class
289
+ * flow with no state machine.
290
+ */
291
+ outputTypes: string[];
292
+ /**
293
+ * Optional English hint for AI-driven flow-spawn: when should the
294
+ * interpretation engine mint a new instance of this flow (as opposed
295
+ * to advancing an existing one)?
296
+ *
297
+ * Design doc §4.1: analogous to `interpretationHint` on subject
298
+ * classes — steers the LLM's up-front extraction pass. Distinct from
299
+ * `interpretationHint` on the flow, which describes what the flow *is*.
300
+ * Example (Delivery Flow): "Spawn when someone commits to a concrete,
301
+ * actionable task."
302
+ */
303
+ creationHint?: string;
304
+ /**
305
+ * Optional background queries pulled into the LLM prompt as CONTEXT
306
+ * (not evidence).
307
+ *
308
+ * Design doc §4.1: engine evaluates each `ModelQuery` and threads
309
+ * matches into the prompt so the LLM can reason with them, but
310
+ * matches do NOT count toward `requires` guards on states. Same
311
+ * `ModelQuery[]` shape and template-variable rules as `FlowState.requires`.
312
+ * Empty / unset = no context queries.
313
+ */
314
+ context?: ModelQuery[];
315
+ /**
316
+ * Flow-level consensus rule. Two roles:
317
+ * - **Default for state transitions** — when a `FlowState` doesn't
318
+ * declare its own `consensusRule`, transitions into it fall back
319
+ * to this rule.
320
+ * - **Zero-state flow completion** — for actions-as-flows (a flow
321
+ * with no `FlowState`s), this is the rule the engine checks the
322
+ * moment `outputTypes` are satisfied. E.g. a Like flow declares
323
+ * `{ n: 1 }` and completes on the first author.
324
+ *
325
+ * Design doc §4.1: terminal condition for stateless flows.
326
+ * Unset = engine default of `{ n: 1 }` applies at both layers.
327
+ */
328
+ consensusRule?: ConsensusRule;
329
+ /**
330
+ * States in this flow.
331
+ *
332
+ * **Ordering convention (James PR #929 R9):** the array is stored sorted
333
+ * ascending by `value`. `states[0]` is the initial state — the one
334
+ * {@link FlowInstance.start} mints a fresh instance into. A flow author
335
+ * who wants a specific state as the entry point must give it the lowest
336
+ * `value` in the set. `fromLinks` enforces this sort, so link-order on
337
+ * the graph never dictates the initial state.
338
+ */
113
339
  private _states;
114
340
  /** Transitions between states */
115
341
  private _transitions;