@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,28 +1,29 @@
1
- import { buildSPARQLQuery, buildPaginationSubquery, hasJsOnlyWhereFilters } from './query-sparql';
1
+ import { buildSPARQLQuery, buildPaginationSubquery, hasJsOnlyWhereFilters, looksLikeUri, valueToLiteralIri } from './query-sparql';
2
+ import { Literal } from '../Literal';
2
3
 
3
4
  // Minimal stubs for ModelMetadata
4
5
  const emptyMetadata: any = { properties: {}, relations: {} };
5
6
 
6
- // Metadata with a required (non-literal) property and a literal-stored property
7
+ // Metadata with a deterministic-literal property (`name`), a signed-envelope
8
+ // property (`category`, `resolveLanguage: "literal"`), and another
9
+ // deterministic-literal property with an initial value (`description`).
7
10
  const richMetadata: any = {
8
11
  properties: {
9
12
  name: {
10
13
  name: 'name',
11
14
  predicate: 'flux://name',
12
15
  required: true,
13
- resolveLanguage: 'literal',
14
16
  },
15
17
  category: {
16
18
  name: 'category',
17
19
  predicate: 'flux://category',
18
20
  required: true,
19
- resolveLanguage: 'did:lang:abc', // non-literal → URI stored
21
+ resolveLanguage: 'literal', // envelope → expression URI stored
20
22
  },
21
23
  description: {
22
24
  name: 'description',
23
25
  predicate: 'flux://description',
24
26
  initial: 'literal://string:empty',
25
- resolveLanguage: 'literal',
26
27
  },
27
28
  },
28
29
  relations: {},
@@ -41,7 +42,7 @@ describe('hasJsOnlyWhereFilters', () => {
41
42
 
42
43
  it('returns true when where has literal-stored property with comparison operator', () => {
43
44
  // gt/lt/gte/lte/between/contains remain JS-only
44
- const meta: any = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' } }, relations: {} };
45
+ const meta: any = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true } }, relations: {} };
45
46
  expect(hasJsOnlyWhereFilters(meta, emptyRelations, { rating: { gt: 5 } })).toBe(true);
46
47
  });
47
48
 
@@ -113,7 +114,7 @@ describe('buildSPARQLQuery — parse_literal push-down filters', () => {
113
114
  it('does NOT use parse_literal for comparison operators (gt/lt)', () => {
114
115
  const meta: any = {
115
116
  properties: {
116
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
117
+ rating: { name: 'rating', predicate: 'flux://rating', required: true },
117
118
  },
118
119
  relations: {},
119
120
  };
@@ -204,8 +205,8 @@ describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
204
205
  const modelClass: any = {};
205
206
  const mixedMeta: any = {
206
207
  properties: {
207
- name: { name: 'name', predicate: 'flux://name', required: true, resolveLanguage: 'literal' },
208
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
208
+ name: { name: 'name', predicate: 'flux://name', required: true },
209
+ rating: { name: 'rating', predicate: 'flux://rating', required: true },
209
210
  },
210
211
  relations: {},
211
212
  };
@@ -224,10 +225,14 @@ describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
224
225
  describe('buildSPARQLQuery — non-literal and flag properties', () => {
225
226
  const modelClass: any = {};
226
227
 
227
- it('does NOT use parse_literal for non-literal (resolveLanguage) properties', () => {
228
+ it('does NOT use parse_literal for envelope (resolveLanguage: "literal") properties', () => {
229
+ // Envelope properties store signed expression URIs in the target position,
230
+ // not raw literals — the value comparison happens on the unwrapped inner
231
+ // data via a different code path (Rust `parse_literal_fn`), not by the JS
232
+ // WHERE builder emitting a `<ad4m://fn/parse_literal>` filter here.
228
233
  const meta: any = {
229
234
  properties: {
230
- avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: 'did:lang:some-language' },
235
+ avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: 'literal' },
231
236
  },
232
237
  relations: {},
233
238
  };
@@ -312,7 +317,7 @@ describe('SPARQL-level pagination', () => {
312
317
  it('does NOT push pagination to SPARQL when JS-only where filters exist (gt operator)', () => {
313
318
  const meta: any = {
314
319
  properties: {
315
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
320
+ rating: { name: 'rating', predicate: 'flux://rating', required: true },
316
321
  },
317
322
  relations: {},
318
323
  };
@@ -340,7 +345,7 @@ describe('buildSPARQLQuery — set-difference patterns', () => {
340
345
  it('generates global EXISTS without parent scoping when no parent filter', () => {
341
346
  const meta: any = {
342
347
  properties: {
343
- status: { name: 'status', predicate: 'flux://status', required: true, resolveLanguage: 'literal' },
348
+ status: { name: 'status', predicate: 'flux://status', required: true },
344
349
  },
345
350
  relations: {},
346
351
  };
@@ -522,3 +527,99 @@ describe('buildSPARQLQuery — OR/AND/NOT not emitted as SPARQL (handled Rust-si
522
527
  expect(sparql).not.toContain('LIMIT');
523
528
  });
524
529
  });
530
+
531
+ // ──────────────────────────────────────────────────────────
532
+ // valueToLiteralIri — object/array encoding parity with Rust
533
+ // ──────────────────────────────────────────────────────────
534
+
535
+ describe('valueToLiteralIri', () => {
536
+ it('encodes plain objects as literal:json:* and round-trips', () => {
537
+ const url = valueToLiteralIri({ a: 1 });
538
+ expect(url.startsWith('literal:json:')).toBe(true);
539
+ // Regression: previously fell through to String(value) → "[object Object]"
540
+ expect(url).not.toContain('object%20Object');
541
+ expect(Literal.fromUrl(url).get()).toEqual({ a: 1 });
542
+ });
543
+
544
+ it('encodes arrays as literal:json:* and round-trips', () => {
545
+ const url = valueToLiteralIri([1, 2, 3]);
546
+ expect(url.startsWith('literal:json:')).toBe(true);
547
+ // Regression: previously stringified to "1,2,3"
548
+ expect(url).not.toBe('literal:string:1%2C2%2C3');
549
+ expect(Literal.fromUrl(url).get()).toEqual([1, 2, 3]);
550
+ });
551
+
552
+ it('encodes nested objects and round-trips', () => {
553
+ const url = valueToLiteralIri({ nested: { b: 2 } });
554
+ expect(url.startsWith('literal:json:')).toBe(true);
555
+ expect(Literal.fromUrl(url).get()).toEqual({ nested: { b: 2 } });
556
+ });
557
+
558
+ it('preserves string encoding (non-URI)', () => {
559
+ const url = valueToLiteralIri('hello world');
560
+ expect(url).toBe('literal:string:hello%20world');
561
+ expect(Literal.fromUrl(url).get()).toBe('hello world');
562
+ });
563
+
564
+ it('returns URI-like strings unchanged', () => {
565
+ expect(valueToLiteralIri('https://example.com/thing')).toBe('https://example.com/thing');
566
+ });
567
+
568
+ it('encodes numbers as literal:number:*', () => {
569
+ const url = valueToLiteralIri(42);
570
+ expect(url).toBe('literal:number:42');
571
+ expect(Literal.fromUrl(url).get()).toBe(42);
572
+ });
573
+
574
+ it('encodes booleans as literal:boolean:*', () => {
575
+ const url = valueToLiteralIri(true);
576
+ expect(url).toBe('literal:boolean:true');
577
+ expect(Literal.fromUrl(url).get()).toBe(true);
578
+ });
579
+
580
+ it('encodes null via the String() fallthrough as literal:string:null', () => {
581
+ // `null` is `typeof 'object'` in JS, but `Literal.from(null).toUrl()`
582
+ // throws on the empty-literal check, so the `value !== null` guard
583
+ // deliberately keeps `null` on the historical fallthrough path.
584
+ const url = valueToLiteralIri(null);
585
+ expect(url).toBe('literal:string:null');
586
+ expect(Literal.fromUrl(url).get()).toBe('null');
587
+ });
588
+ });
589
+
590
+
591
+ // ---------------------------------------------------------------------------
592
+ // looksLikeUri — shared write-side predicate that MUST agree with the
593
+ // Rust-side `is_safe_iri_target` / `looks_like_absolute_iri`. See the
594
+ // doc comment on `looksLikeUri` for why drift produces silent no-match
595
+ // reads (PR #874).
596
+ // ---------------------------------------------------------------------------
597
+ describe('looksLikeUri', () => {
598
+ it('accepts well-formed absolute IRIs', () => {
599
+ expect(looksLikeUri('did:key:z6Mk123')).toBe(true);
600
+ expect(looksLikeUri('literal:string:hello')).toBe(true);
601
+ expect(looksLikeUri('http://example.com/foo')).toBe(true);
602
+ });
603
+
604
+ it('rejects scheme-lookalike prose that would fail Rust validate_iri', () => {
605
+ expect(looksLikeUri('Note: buy milk')).toBe(false);
606
+ expect(looksLikeUri('Re: standup')).toBe(false);
607
+ expect(looksLikeUri('TODO: fix this')).toBe(false);
608
+ });
609
+
610
+ it('rejects control chars, whitespace, and SPARQL-breaking chars', () => {
611
+ expect(looksLikeUri('tag:2025:new\nline')).toBe(false);
612
+ expect(looksLikeUri('tag:2025:tab\there')).toBe(false);
613
+ expect(looksLikeUri('http://example.com/foo bar')).toBe(false);
614
+ expect(looksLikeUri('foo:<bar>')).toBe(false);
615
+ expect(looksLikeUri('foo:{bar}')).toBe(false);
616
+ expect(looksLikeUri('foo:"quoted')).toBe(false);
617
+ });
618
+
619
+ it('rejects non-IRI shapes', () => {
620
+ expect(looksLikeUri('just plain text')).toBe(false);
621
+ expect(looksLikeUri('42')).toBe(false);
622
+ expect(looksLikeUri(':no-scheme')).toBe(false);
623
+ expect(looksLikeUri('1abc:foo')).toBe(false);
624
+ });
625
+ });
@@ -81,18 +81,53 @@ export function hasJsOnlyWhereFilters(
81
81
  }
82
82
 
83
83
  /**
84
- * Check if a string value looks like a URI (has a scheme).
84
+ * Check whether a string value is a well-formed absolute IRI that can be
85
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
86
+ * wrapped in a `literal:string:*` URI.
87
+ *
88
+ * This mirrors the Rust `is_safe_iri_target` /
89
+ * `looks_like_absolute_iri` predicate in
90
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
91
+ * **load-bearing**: a value that returns `true` here MUST also be safely
92
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
93
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
94
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
95
+ * through the write regex, is stored as an invalid `NamedNode`, and
96
+ * becomes a silent no-match on read.
97
+ *
98
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
99
+ * same rejection set the Rust `validate_iri` applies: any Unicode
100
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
101
+ * `< > { } "`.
85
102
  */
86
- function looksLikeUri(value: string): boolean {
87
- return /^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value);
103
+ export function looksLikeUri(value: string): boolean {
104
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value)) return false;
105
+ // Reject anything the Rust-side `validate_iri` rejects so the two
106
+ // predicates stay in sync. `\s` covers ASCII whitespace *and*
107
+ // U+00A0/other Unicode whitespace under the default JS regex semantics.
108
+ if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value)) return false;
109
+ return true;
88
110
  }
89
111
 
90
112
  /**
91
113
  * Convert a JS value to its literal: IRI form, matching how the Rust executor
92
- * stores property values that don't have a resolveLanguage set.
93
- * Strings that already look like URIs are returned as-is.
114
+ * stores property values in the default deterministic-literal path
115
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
116
+ * as-is.
117
+ *
118
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
119
+ * resolve path) can keep their on-disk form aligned with what
120
+ * `queryToSPARQL()` filters against — otherwise the same value can be
121
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
122
+ * builders probe `<https://example.com>` from the other.
123
+ *
124
+ * The object/array arm mirrors Rust's `Literal::from_json` in
125
+ * `perspective_instance.rs::resolve_property_value` (which routes
126
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
127
+ * would fall through to `String(value)` and turn `{a: 1}` into
128
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
94
129
  */
95
- function valueToLiteralIri(value: any): string {
130
+ export function valueToLiteralIri(value: any): string {
96
131
  if (typeof value === 'string') {
97
132
  if (looksLikeUri(value)) return value;
98
133
  return Literal.from(value).toUrl();
@@ -103,21 +138,55 @@ function valueToLiteralIri(value: any): string {
103
138
  if (typeof value === 'boolean') {
104
139
  return Literal.from(value).toUrl();
105
140
  }
141
+ // Objects and arrays: route through Literal.from so we emit
142
+ // `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
143
+ // arm we fall through to `String(value)` which turns objects into
144
+ // `"[object Object]"` and arrays into `"1,2"` — silently storing the
145
+ // wrong shape and breaking equality filters (`findAll({ where:
146
+ // { config: {...} } })` would match against `"[object Object]"`).
147
+ // The `value !== null` guard preserves the historical fallthrough for
148
+ // `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
149
+ // throws on the empty-literal check.
150
+ if (value !== null && typeof value === 'object') {
151
+ return Literal.from(value).toUrl();
152
+ }
106
153
  return Literal.from(String(value)).toUrl();
107
154
  }
108
155
 
156
+ /** How a property's value is stored / resolved. */
157
+ export type LiteralStorageMode =
158
+ | { kind: "deterministic" } // deterministic literal: IRI (POS-index friendly, no signature)
159
+ | { kind: "envelope" } // signed expression on the built-in literal language
160
+ | { kind: "custom"; language: string }; // signed expression on a custom language
161
+
162
+ /**
163
+ * Derive the effective storage mode from a property's explicit options.
164
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
165
+ * decorator level:
166
+ * - unset → deterministic typed literal (the perf default
167
+ * for a plain `@Property()`)
168
+ * - `"literal"` → signed envelope on the built-in literal language
169
+ * (per-value provenance, e.g. Flux message bodies)
170
+ * - `<custom address>` → signed expression on that custom language
171
+ */
172
+ export function effectiveLiteralStorage(meta: {
173
+ resolveLanguage?: string;
174
+ }): LiteralStorageMode {
175
+ const lang = meta.resolveLanguage;
176
+ if (lang === undefined) return { kind: "deterministic" };
177
+ if (lang === "literal") return { kind: "envelope" };
178
+ return { kind: "custom", language: lang };
179
+ }
180
+
109
181
  /**
110
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
111
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
112
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
113
- * (e.g. file storage) or flag properties store raw URIs.
182
+ * Determine if a property stores values as deterministic literal: IRIs (so WHERE
183
+ * filters can match typed literals directly). Envelope / custom-language
184
+ * properties resolve through expressions, and flag properties store raw URIs —
185
+ * none is a deterministic literal.
114
186
  */
115
187
  function isLiteralStoredProperty(propMeta: PropertyMetadata): boolean {
116
188
  if (propMeta.flag) return false;
117
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
118
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal") return false;
119
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
120
- return true;
189
+ return effectiveLiteralStorage(propMeta).kind === "deterministic";
121
190
  }
122
191
 
123
192
  /**
@@ -47,20 +47,25 @@ export function formatQueryValue(value: any): string {
47
47
  *
48
48
  * @param predicate - The predicate URI for the property
49
49
  * @param condition - The Where condition value
50
- * @param opts - Optional settings (e.g. `resolveLanguage`)
50
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
51
+ * `true`) selects the direct typed-literal WHERE path.
52
+ * Set to `false` when the property stores a signed
53
+ * envelope (`resolveLanguage: "literal"`) or a
54
+ * custom-language expression — the envelope path unwraps
55
+ * with `parse_literal` before comparing.
51
56
  * @returns A single SPARQL condition string
52
57
  */
53
58
  export function buildWhereCondition(
54
59
  predicate: string,
55
60
  condition: WhereCondition,
56
- opts?: { resolveLanguage?: string; varIndex?: number },
61
+ opts?: { isDeterministicLiteral?: boolean; varIndex?: number },
57
62
  ): string {
58
63
  const escapedPredicate = escapeQueryString(predicate);
59
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
60
- // For language-resolved properties, we match against the plain URI
61
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
62
- // For language-resolved properties, values are plain URIs
63
- const isLiteral = !opts?.resolveLanguage || opts.resolveLanguage === 'literal';
64
+ // For deterministic-literal properties, values are stored as typed
65
+ // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
66
+ // IRI form). For envelope / custom-language properties the target is a
67
+ // signed expression URI; comparisons need to unwrap via `parse_literal`.
68
+ const isLiteral = opts?.isDeterministicLiteral !== false;
64
69
 
65
70
  const varSuffix = opts?.varIndex ?? 0;
66
71
 
@@ -183,23 +188,28 @@ export function compileWhereClause(
183
188
  if (['id', 'author', 'timestamp'].includes(propertyName)) continue;
184
189
 
185
190
  let predicate: string;
186
- let resolveLanguage: string | undefined;
191
+ // Storage mode is derived from `resolveLanguage` alone:
192
+ // - undefined → deterministic typed literal (fast POS-index path)
193
+ // - "literal" → signed envelope on the literal language
194
+ // - custom address → expression on that custom language
195
+ // Envelope and custom-language properties both need the `parse_literal`
196
+ // unwrap path, so we treat any `resolveLanguage`-carrying property as
197
+ // non-deterministic here.
198
+ let isDeterministicLiteral: boolean | undefined;
187
199
 
188
200
  if (metadata) {
189
201
  const propMeta = metadata.properties[propertyName];
190
202
  if (propMeta) {
191
203
  predicate = propMeta.predicate;
192
- resolveLanguage = propMeta.resolveLanguage;
204
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
193
205
  } else {
194
- // Property not found in metadata — treat name as raw predicate URI
195
206
  predicate = propertyName;
196
207
  }
197
208
  } else {
198
- // No metadata — treat name as raw predicate URI
199
209
  predicate = propertyName;
200
210
  }
201
211
 
202
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
212
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
203
213
  if (cond) {
204
214
  conditions.push(cond);
205
215
  }
@@ -394,17 +394,44 @@ describe("Ad4mModel.getModelMetadata() relation filtering fields", () => {
394
394
  // ============================================================================
395
395
 
396
396
  describe("Relation decorator validation", () => {
397
- it("should throw if both getter and target are provided", () => {
398
- expect(() => {
399
- @Model({ name: "InvalidGetterTarget" })
400
- class _Invalid extends Ad4mModel {
401
- @HasMany({
402
- getter: "SELECT ?target WHERE { ?target ?p ?source . }",
403
- target: () => FlaggedTarget,
404
- })
405
- items: string[] = [];
406
- }
407
- }).toThrow(/getter.*target.*mutually exclusive/i);
397
+ it("accepts getter together with target, and keeps the getter verbatim", () => {
398
+ // `target` does two separable jobs — derive a conformance getter, and name
399
+ // the class values hydrate into. Only the first conflicts with an explicit
400
+ // getter, so the pair is legal and the explicit getter wins.
401
+ @Model({ name: "GetterWithTarget" })
402
+ class GetterWithTarget extends Ad4mModel {
403
+ @HasMany({
404
+ getter: "SELECT ?target WHERE { ?rel <we://src> <Base> . ?rel <we://tgt> ?target . }",
405
+ target: () => FlaggedTarget,
406
+ })
407
+ items: string[] = [];
408
+ }
409
+
410
+ const { shape } = (GetterWithTarget as any).generateSHACL();
411
+ const rel = shape.properties.find((p: any) => p.name === "items");
412
+
413
+ expect(rel.getter).toBe(
414
+ "SELECT ?target WHERE { ?rel <we://src> <Base> . ?rel <we://tgt> ?target . }"
415
+ );
416
+ });
417
+
418
+ it("emits sh:class for a getter relation, so include has a shape to resolve", () => {
419
+ // Without a target class the executor resolves a shape named "" and the
420
+ // include fails — which is what made a custom traversal able to return only
421
+ // bare URIs.
422
+ @Model({ name: "GetterWithTargetClass" })
423
+ class GetterWithTargetClass extends Ad4mModel {
424
+ @HasMany({
425
+ getter: "SELECT ?target WHERE { ?target ?p <Base> . }",
426
+ target: () => FlaggedTarget,
427
+ })
428
+ items: string[] = [];
429
+ }
430
+
431
+ const { shape } = (GetterWithTargetClass as any).generateSHACL();
432
+ const rel = shape.properties.find((p: any) => p.name === "items");
433
+
434
+ expect(rel.targetClassName).toBe("FlaggedTarget");
408
435
  });
409
436
 
410
437
  it("should throw if both getter and through are provided", () => {
@@ -556,25 +583,48 @@ describe("sh:class target shape reference", () => {
556
583
  // ============================================================================
557
584
 
558
585
  describe("where clause validation", () => {
559
- it("should throw if both where and getter are provided", () => {
586
+ it("accepts where alongside a getter, as a post-getter filter", () => {
587
+ // The executor applies where filters specifically to getter-backed
588
+ // relations (`apply_where_filter_to_relation`), so the runtime was built
589
+ // for this pairing; only the decorator refused it.
590
+ @Model({ name: "WhereWithGetter" })
591
+ class WhereWithGetter extends Ad4mModel {
592
+ @HasMany({
593
+ where: { status: "active" },
594
+ getter: "SELECT ?target WHERE { ?target ?p <Base> . }",
595
+ target: () => FlaggedTarget,
596
+ })
597
+ items: string[] = [];
598
+ }
599
+
600
+ const { shape } = (WhereWithGetter as any).generateSHACL();
601
+ const rel = shape.properties.find((p: any) => p.name === "items");
602
+
603
+ expect(rel.whereFilter).toEqual({ status: "active" });
604
+ expect(rel.getter).toBe("SELECT ?target WHERE { ?target ?p <Base> . }");
605
+ });
606
+
607
+ it("should throw if both where and filter:false are provided", () => {
560
608
  expect(() => {
561
- @Model({ name: "InvalidWhereGetter" })
609
+ @Model({ name: "InvalidWhereFilterFalse" })
562
610
  class _Invalid extends Ad4mModel {
563
- @HasMany({
611
+ @HasMany(() => FlaggedTarget, {
612
+ through: "test://pred",
564
613
  where: { status: "active" },
565
- getter: "SELECT ?target WHERE { ?target ?p ?source . }",
614
+ filter: false,
566
615
  })
567
616
  items: string[] = [];
568
617
  }
569
- }).toThrow(/where.*getter.*mutually exclusive/i);
618
+ }).toThrow(/where.*filter.*contradictory/i);
570
619
  });
571
620
 
572
- it("should throw if both where and filter:false are provided", () => {
621
+ it("should throw if both where and filter:false are provided on a getter relation", () => {
573
622
  expect(() => {
574
- @Model({ name: "InvalidWhereFilterFalse" })
623
+ @Model({ name: "InvalidGetterWhereFilterFalse" })
575
624
  class _Invalid extends Ad4mModel {
576
- @HasMany(() => FlaggedTarget, {
577
- through: "test://pred",
625
+ @HasMany({
626
+ getter: "SELECT ?target WHERE { ?target ?p <Base> . }",
627
+ target: () => FlaggedTarget,
578
628
  where: { status: "active" },
579
629
  filter: false,
580
630
  })
@@ -129,17 +129,36 @@ export function buildSHACL(
129
129
  path: propMeta.through,
130
130
  };
131
131
 
132
- // Determine datatype from initial value or resolveLanguage
133
- if (propMeta.resolveLanguage === "literal") {
134
- propShape.datatype = "xsd://string";
135
- } else if (propMeta.initial) {
136
- const initialType = typeof obj[propName];
137
- if (initialType === "number") {
138
- propShape.datatype = "xsd://integer";
139
- } else if (initialType === "boolean") {
140
- propShape.datatype = "xsd://boolean";
141
- } else if (initialType === "string") {
142
- propShape.datatype = "xsd://string";
132
+ // Determine datatype from JS field value type; the resolve* options
133
+ // control storage mode (deterministic vs envelope), not scalar type.
134
+ // A value stored on the literal language (deterministic or envelope,
135
+ // i.e. resolveLanguage unset or "literal") gets a string datatype when
136
+ // no initial value pins a more specific type. A custom resolveLanguage
137
+ // yields an expression URI, not a literal.
138
+ //
139
+ // Skip auto-datatype for properties with a custom `getter` — those
140
+ // typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
141
+ // that hops through a link to another instance's URI). Autosetting
142
+ // `sh:datatype xsd:string` there would trip the hydration decode gate
143
+ // and silently transform `literal:string:<hex>` URIs into their inner
144
+ // plain-string form on read. Users who want a getter to return literal
145
+ // values can opt in explicitly by setting `datatype` on the property
146
+ // options (handled below).
147
+ if (propMeta.datatype) {
148
+ // Explicit opt-in from PropertyOptions always wins over inference.
149
+ propShape.datatype = propMeta.datatype;
150
+ } else {
151
+ const isLiteral =
152
+ propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
153
+ if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
154
+ const initialType = typeof obj[propName];
155
+ if (initialType === "number") {
156
+ propShape.datatype = "xsd://integer";
157
+ } else if (initialType === "boolean") {
158
+ propShape.datatype = "xsd://boolean";
159
+ } else if (initialType === "string" || isLiteral) {
160
+ propShape.datatype = "xsd://string";
161
+ }
143
162
  }
144
163
  }
145
164
 
@@ -261,8 +280,18 @@ export function buildSHACL(
261
280
  path: synthesizedPath,
262
281
  };
263
282
 
264
- // Relations typically contain IRIs
265
- relShape.nodeKind = 'IRI';
283
+ // A relation with a declared `datatype` holds encoded literal
284
+ // values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
285
+ // Everything else is a URI relation pointing at another
286
+ // instance. The executor uses `sh:datatype` on hydration to
287
+ // decide whether to decode `literal:<type>:<value>` wire form
288
+ // (yes for literals, no for URIs).
289
+ if (relMeta.datatype) {
290
+ relShape.datatype = relMeta.datatype;
291
+ relShape.nodeKind = 'Literal';
292
+ } else {
293
+ relShape.nodeKind = 'IRI';
294
+ }
266
295
 
267
296
  // Encode relation kind so the executor can derive direction and
268
297
  // scalar-vs-collection rendering without consulting the JS class.
@@ -280,11 +309,27 @@ export function buildSHACL(
280
309
  relShape.filter = false;
281
310
  }
282
311
 
312
+ // Ordering is declared in the type system so the executor can act on it
313
+ // for every writer, not just this client.
314
+ if (relMeta.ordering) {
315
+ relShape.ordering = relMeta.ordering.strategy;
316
+ }
317
+
283
318
  // AD4M-specific metadata
284
319
  if (relMeta.local !== undefined) {
285
320
  relShape.local = relMeta.local;
286
321
  }
287
322
 
323
+ // Per-relation interpretation hint — sentence-level meaning that
324
+ // steers the harness LLM's `_propose_link_child` `predicate` field
325
+ // description. Read back on the Rust side by
326
+ // `ShaclProperty.interpretation_hint` and rendered into the tool
327
+ // schema alongside the predicate URI enum (so `basedOn` reads
328
+ // "prior beliefs this intention derives from", not just "some link").
329
+ if (relMeta.interpretationHint) {
330
+ relShape.interpretationHint = relMeta.interpretationHint;
331
+ }
332
+
288
333
  // Adder / Remover actions — only meaningful for relations backed
289
334
  // by a real link predicate. Getter-only relations are read-only.
290
335
  if (relMeta.predicate) {
@@ -426,6 +471,26 @@ export function buildSHACL(
426
471
  shape.addProperty(relShape);
427
472
  }
428
473
 
474
+ // ── Ordering links ─────────────────────────────────────────────────
475
+ // Ordering entries are stored on the *parent*, under one shared predicate,
476
+ // so that reconstruction needs no extra query: they arrive with the
477
+ // instance's own links. That only works if the instance query asks for them,
478
+ // and it builds its predicate filter from the shape's declared paths — so a
479
+ // class owning any ordered collection has to declare the predicate, or the
480
+ // very links the ordering depends on are filtered out of the read that needs
481
+ // them.
482
+ //
483
+ // One entry covers every ordered relation on the class; each entry names the
484
+ // relation it belongs to.
485
+ const hasOrderedRelation = Object.values(allRelationsMeta).some((m) => m.ordering);
486
+ if (hasOrderedRelation) {
487
+ shape.addProperty({
488
+ name: '_collectionOrder',
489
+ path: 'ad4m://collection_order',
490
+ nodeKind: 'IRI',
491
+ });
492
+ }
493
+
429
494
  // Always set constructor and destructor actions on the shape, even
430
495
  // when empty. An empty array serialises to `literal:string:[]`
431
496
  // which the Rust executor parses as a valid (no-op) command list,