@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
@@ -18,7 +18,7 @@ describe("Ad4mModel.getModelMetadata()", () => {
18
18
  it("should extract property metadata with all fields", () => {
19
19
  @Model({ name: "PropertyModel" })
20
20
  class PropertyModel extends Ad4mModel {
21
- @Property({ through: "test://name", resolveLanguage: "literal" })
21
+ @Property({ through: "test://name" })
22
22
  name: string = "";
23
23
 
24
24
  @Optional({ through: "test://optional" })
@@ -40,7 +40,9 @@ describe("Ad4mModel.getModelMetadata()", () => {
40
40
  expect(metadata.properties.name.predicate).toBe("test://name");
41
41
  expect(metadata.properties.name.required).toBe(false);
42
42
  expect(metadata.properties.name.readOnly).toBe(false);
43
- expect(metadata.properties.name.resolveLanguage).toBe("literal");
43
+ // A bare @Property has no resolveLanguage → deterministic typed literal
44
+ // storage (default fast path).
45
+ expect(metadata.properties.name.resolveLanguage).toBeUndefined();
44
46
 
45
47
  // Verify "optional" property
46
48
  expect(metadata.properties.optional.predicate).toBe("test://optional");
@@ -148,7 +150,7 @@ describe("Ad4mModel.getModelMetadata()", () => {
148
150
  it("should handle complex model with mixed property and relation types", () => {
149
151
  @Model({ name: "Recipe" })
150
152
  class Recipe extends Ad4mModel {
151
- @Property({ through: "recipe://name", resolveLanguage: "literal" })
153
+ @Property({ through: "recipe://name" })
152
154
  name: string = "";
153
155
 
154
156
  @Optional({ through: "recipe://description" })
@@ -182,7 +184,8 @@ describe("Ad4mModel.getModelMetadata()", () => {
182
184
 
183
185
  // Verify all metadata fields are correctly extracted
184
186
  expect(metadata.properties.name.predicate).toBe("recipe://name");
185
- expect(metadata.properties.name.resolveLanguage).toBe("literal");
187
+ // Bare @Property → no resolveLanguage → deterministic typed literal.
188
+ expect(metadata.properties.name.resolveLanguage).toBeUndefined();
186
189
  expect(metadata.properties.description.predicate).toBe("recipe://description");
187
190
  expect(metadata.properties.rating.predicate).toBe("recipe://rating");
188
191
  expect(metadata.properties.rating.prologGetter).toBe("avg_rating(Base, Value)");
@@ -207,8 +210,7 @@ describe("Ad4mModel.fromJSONSchema() with getModelMetadata()", () => {
207
210
 
208
211
  const ProductClass = Ad4mModel.fromJSONSchema(schema, {
209
212
  name: "Product",
210
- namespace: "product://",
211
- resolveLanguage: "literal"
213
+ namespace: "product://"
212
214
  });
213
215
 
214
216
  const metadata = ProductClass.getModelMetadata();
@@ -222,12 +224,13 @@ describe("Ad4mModel.fromJSONSchema() with getModelMetadata()", () => {
222
224
  expect(metadata.properties.name.predicate).toBe("product://name");
223
225
  expect(metadata.properties.name.required).toBe(true);
224
226
  expect(metadata.properties.name.readOnly).toBe(false);
225
- expect(metadata.properties.name.resolveLanguage).toBe("literal");
227
+ // No resolveLanguage set → deterministic typed literal storage (default).
228
+ expect(metadata.properties.name.resolveLanguage).toBeUndefined();
226
229
 
227
230
  expect(metadata.properties.price).toBeDefined();
228
231
  expect(metadata.properties.price.predicate).toBe("product://price");
229
232
  expect(metadata.properties.price.required).toBe(true);
230
- expect(metadata.properties.price.resolveLanguage).toBe("literal");
233
+ expect(metadata.properties.price.resolveLanguage).toBeUndefined();
231
234
 
232
235
  expect(metadata.properties.description).toBeDefined();
233
236
  expect(metadata.properties.description.predicate).toBe("product://description");
@@ -288,7 +291,6 @@ describe("Ad4mModel.fromJSONSchema() with getModelMetadata()", () => {
288
291
  type: "string",
289
292
  "x-ad4m": {
290
293
  through: "foaf://name",
291
- resolveLanguage: "literal",
292
294
  writable: true
293
295
  }
294
296
  },
@@ -311,7 +313,8 @@ describe("Ad4mModel.fromJSONSchema() with getModelMetadata()", () => {
311
313
 
312
314
  // Verify x-ad4m metadata is respected
313
315
  expect(metadata.properties.name.predicate).toBe("foaf://name");
314
- expect(metadata.properties.name.resolveLanguage).toBe("literal");
316
+ // No resolveLanguage set → deterministic typed literal (default).
317
+ expect(metadata.properties.name.resolveLanguage).toBeUndefined();
315
318
  expect(metadata.properties.name.readOnly).toBe(false);
316
319
  expect(metadata.properties.name.required).toBe(true);
317
320
 
@@ -371,8 +374,7 @@ describe("Ad4mModel.fromJSONSchema() with getModelMetadata()", () => {
371
374
 
372
375
  const ArticleClass = Ad4mModel.fromJSONSchema(schema, {
373
376
  name: "Article",
374
- namespace: "article://",
375
- resolveLanguage: "literal"
377
+ namespace: "article://"
376
378
  });
377
379
 
378
380
  const metadata = ArticleClass.getModelMetadata();
@@ -384,11 +386,12 @@ describe("Ad4mModel.fromJSONSchema() with getModelMetadata()", () => {
384
386
  expect(metadata.properties.title).toBeDefined();
385
387
  expect(metadata.properties.title.predicate).toBe("article://title");
386
388
  expect(metadata.properties.title.required).toBe(true);
387
- expect(metadata.properties.title.resolveLanguage).toBe("literal");
389
+ // No resolveLanguage set → deterministic typed literal (default).
390
+ expect(metadata.properties.title.resolveLanguage).toBeUndefined();
388
391
 
389
392
  expect(metadata.properties.views).toBeDefined();
390
393
  expect(metadata.properties.views.predicate).toBe("article://views");
391
- expect(metadata.properties.views.resolveLanguage).toBe("literal");
394
+ expect(metadata.properties.views.resolveLanguage).toBeUndefined();
392
395
 
393
396
  expect(metadata.properties.published).toBeDefined();
394
397
  expect(metadata.properties.published.predicate).toBe("article://published");
@@ -522,13 +525,13 @@ describe("Ad4mModel.queryToSPARQL()", () => {
522
525
 
523
526
  @Model({ name: "Task" })
524
527
  class Task extends Ad4mModel {
525
- @Property({ through: "task://title", resolveLanguage: "literal", required: true })
528
+ @Property({ through: "task://title", required: true })
526
529
  title: string = "";
527
530
 
528
- @Property({ through: "task://priority", resolveLanguage: "literal" })
531
+ @Property({ through: "task://priority" })
529
532
  priority: number = 0;
530
533
 
531
- @Property({ through: "task://done", resolveLanguage: "literal" })
534
+ @Property({ through: "task://done" })
532
535
  done: boolean = false;
533
536
 
534
537
  @Optional({ through: "task://description" })
@@ -951,7 +954,7 @@ describe("SPARQL direct triple pattern generation", () => {
951
954
  @Flag({ through: "flux://entry_type", value: "flux://channel" })
952
955
  type: string = "";
953
956
 
954
- @Property({ through: "flux://name", resolveLanguage: "literal", required: true })
957
+ @Property({ through: "flux://name", required: true })
955
958
  name: string = "";
956
959
 
957
960
  @Optional({ through: "flux://description" })
@@ -1034,13 +1037,13 @@ describe("buildSPARQLQuery edge cases", () => {
1034
1037
  @Flag({ through: "flag://type", value: "flag://FlagModel" })
1035
1038
  type: string = "";
1036
1039
 
1037
- @Property({ through: "flag://name", resolveLanguage: "literal", required: true })
1040
+ @Property({ through: "flag://name", required: true })
1038
1041
  name: string = "";
1039
1042
  }
1040
1043
 
1041
1044
  @Model({ name: "NoFlagModel" })
1042
1045
  class NoFlagModel extends Ad4mModel {
1043
- @Property({ through: "noflag://title", resolveLanguage: "literal" })
1046
+ @Property({ through: "noflag://title" })
1044
1047
  title: string = "";
1045
1048
  }
1046
1049
 
@@ -1735,7 +1738,7 @@ describe("SHACL recursion — self-referential relations", () => {
1735
1738
  it("should generate SHACL for a directly self-referential model without overflowing the stack", () => {
1736
1739
  @Model({ name: "RecursiveChannel" })
1737
1740
  class RecursiveChannel extends Ad4mModel {
1738
- @Property({ through: "channel://name", resolveLanguage: "literal" })
1741
+ @Property({ through: "channel://name" })
1739
1742
  name: string = "";
1740
1743
 
1741
1744
  @HasMany(() => RecursiveChannel, { through: "channel://child" })
@@ -1862,7 +1865,7 @@ describe("deepQuery — getter evaluation", () => {
1862
1865
  @Flag({ through: "flux://entry_type", value: "flux://message" })
1863
1866
  type: string = "";
1864
1867
 
1865
- @Property({ through: "flux://body", resolveLanguage: "literal" })
1868
+ @Property({ through: "flux://body" })
1866
1869
  body: string = "";
1867
1870
 
1868
1871
  @Property({
@@ -2432,3 +2435,707 @@ describe("IncludeProjection type guard and key splitting", () => {
2432
2435
  expect((results[0] as any).$signalCount).toBe(5);
2433
2436
  });
2434
2437
  });
2438
+
2439
+ describe("Ad4mModel instance identity (uniqueness without envelopes)", () => {
2440
+ // Without a signed envelope, the only thing that keeps two instances from
2441
+ // collapsing onto the same node is their auto-generated base expression.
2442
+ // These tests pin that guarantee down: identity must come from the
2443
+ // instance's own IRI, never from (possibly duplicate) property content.
2444
+ const mockPerspective = {} as any;
2445
+
2446
+ it("auto-generates a distinct id for every instance, even with identical property values", () => {
2447
+ @Model({ name: "IdentityTestMessage" })
2448
+ class IdentityTestMessage extends Ad4mModel {
2449
+ @Property({ through: "identity://body", resolveLanguage: "literal" })
2450
+ body: string = "";
2451
+ }
2452
+
2453
+ const message1 = new IdentityTestMessage(mockPerspective);
2454
+ const message2 = new IdentityTestMessage(mockPerspective);
2455
+
2456
+ message1.body = "hello";
2457
+ message2.body = "hello";
2458
+
2459
+ expect(message1.body).toBe(message2.body);
2460
+ expect(message1.id).not.toBe(message2.id);
2461
+ });
2462
+
2463
+ it("uses the ad4m://obj/<random> scheme, not content-derived addressing", () => {
2464
+ @Model({ name: "IdentityTestSchemeCheck" })
2465
+ class IdentityTestSchemeCheck extends Ad4mModel {}
2466
+
2467
+ const instance = new IdentityTestSchemeCheck(mockPerspective);
2468
+
2469
+ // 24 lowercase a-z chars after the prefix (see makeRandomId in ./util.ts).
2470
+ // Locks in the scheme so a regression toward hashing property content
2471
+ // for the base expression — which would reintroduce the exact collision
2472
+ // this scheme exists to prevent — fails this test.
2473
+ expect(instance.id).toMatch(/^ad4m:\/\/obj\/[a-z]{24}$/);
2474
+ });
2475
+
2476
+ it("never reuses an id across many instances", () => {
2477
+ @Model({ name: "IdentityTestManyInstances" })
2478
+ class IdentityTestManyInstances extends Ad4mModel {}
2479
+
2480
+ const ids = Array.from(
2481
+ { length: 200 },
2482
+ () => new IdentityTestManyInstances(mockPerspective).id
2483
+ );
2484
+
2485
+ expect(new Set(ids).size).toBe(ids.length);
2486
+ });
2487
+
2488
+ it("respects an explicitly-provided base expression instead of generating one", () => {
2489
+ @Model({ name: "IdentityTestExplicitId" })
2490
+ class IdentityTestExplicitId extends Ad4mModel {}
2491
+
2492
+ const instance = new IdentityTestExplicitId(mockPerspective, "flux://existing-instance");
2493
+
2494
+ expect(instance.id).toBe("flux://existing-instance");
2495
+ });
2496
+ });
2497
+
2498
+ describe("Relation writes: to-one batching and scalar coercion", () => {
2499
+ // `Relationship` is the shape that made both of these visible: a record whose
2500
+ // two to-one relations name the things it connects, so it is worthless until
2501
+ // both endpoints are linked, and it is created and pointed in one gesture.
2502
+ @Model({ name: "TestRelationship" })
2503
+ class TestRelationship extends Ad4mModel {
2504
+ @Flag({ through: "we://flag", value: "we://relationship" })
2505
+ flag: string = "";
2506
+
2507
+ @Property({ through: "we://title", required: true })
2508
+ label: string = "";
2509
+
2510
+ @HasOne({ through: "we://relationship_source" })
2511
+ source?: string;
2512
+
2513
+ @HasOne({ through: "we://relationship_target" })
2514
+ target?: string;
2515
+ }
2516
+
2517
+ // A coverage fixture for a branch that already exists in `save()`, not a
2518
+ // modelling pattern being endorsed. No required property, no flag and no
2519
+ // initial value means `buildSHACL` emits the node shape and its property
2520
+ // shapes as normal but with an *empty* constructor-action list, which the
2521
+ // Rust side rejects as "No SHACL constructor found" — so `save()` skips
2522
+ // `createSubject` and calls `innerUpdate(true)` instead. The base expression
2523
+ // exists either way: the `Ad4mModel` constructor mints one, and
2524
+ // `createSubject` writes onto a base rather than creating it.
2525
+ //
2526
+ // Worth naming the real caveat, which is about conformance rather than
2527
+ // writes: a class with no required property and no flag states no criteria,
2528
+ // so nothing structurally distinguishes an instance of it from any other
2529
+ // base expression. That makes it an overlay rather than a class, and it is a
2530
+ // question about SDNA modelling generally rather than about this file.
2531
+ @Model({ name: "TestNoConstructor" })
2532
+ class TestNoConstructor extends Ad4mModel {
2533
+ @HasOne({ through: "we://placed_node" })
2534
+ node?: string;
2535
+ }
2536
+
2537
+ const makePerspective = () =>
2538
+ ({
2539
+ executeAction: jest.fn().mockResolvedValue(undefined),
2540
+ createSubject: jest.fn().mockResolvedValue(undefined),
2541
+ createBatch: jest.fn().mockResolvedValue("batch-generated"),
2542
+ commitBatch: jest.fn().mockResolvedValue(undefined),
2543
+ stringOrTemplateObjectToSubjectClassName: jest
2544
+ .fn()
2545
+ .mockResolvedValue("TestRelationship"),
2546
+ uuid: "test-perspective-uuid",
2547
+ }) as any;
2548
+
2549
+ /** Targets written by `executeAction`, across every call. */
2550
+ const writtenTargets = (perspective: any): string[] =>
2551
+ perspective.executeAction.mock.calls.flatMap((call: any[]) =>
2552
+ (call[2] ?? []).map((param: any) => param.value)
2553
+ );
2554
+
2555
+ /** The batchId argument of each `executeAction` call. */
2556
+ const batchIds = (perspective: any): unknown[] =>
2557
+ perspective.executeAction.mock.calls.map((call: any[]) => call[3]);
2558
+
2559
+ describe("a scalar handed to a relation field", () => {
2560
+ it("writes a link instead of being silently dropped", async () => {
2561
+ // The failure this closes: this call typechecked, ran, resolved, and
2562
+ // wrote no link — leaving a relationship with no endpoints, which only
2563
+ // surfaces later as a reader calling the record malformed.
2564
+ const perspective = makePerspective();
2565
+
2566
+ await TestRelationship.create(
2567
+ perspective,
2568
+ { label: "contradicts", source: "we://block/a", target: "we://block/b" },
2569
+ { batchId: "batch-1" }
2570
+ );
2571
+
2572
+ expect(writtenTargets(perspective)).toEqual(
2573
+ expect.arrayContaining(["we://block/a", "we://block/b"])
2574
+ );
2575
+ });
2576
+
2577
+ it("writes it even when a constructor consumed the properties", async () => {
2578
+ // `create` passes `setProperties: false` when the class has a SHACL
2579
+ // constructor, because `createSubject` writes the values map. A relation
2580
+ // carries `ad4m://adder` rather than `ad4m://setter`, so `createSubject`
2581
+ // drops it — meaning the relation write has to happen here regardless of
2582
+ // that flag, or both paths discard it at once.
2583
+ const perspective = makePerspective();
2584
+
2585
+ await TestRelationship.create(
2586
+ perspective,
2587
+ { label: "contradicts", source: "we://block/a" },
2588
+ { batchId: "batch-1" }
2589
+ );
2590
+
2591
+ expect(perspective.createSubject).toHaveBeenCalled();
2592
+ expect(writtenTargets(perspective)).toContain("we://block/a");
2593
+ });
2594
+
2595
+ it("agrees with the documented array form", async () => {
2596
+ const scalar = makePerspective();
2597
+ await TestRelationship.create(
2598
+ scalar,
2599
+ { label: "x", source: "we://block/a" },
2600
+ { batchId: "b" }
2601
+ );
2602
+
2603
+ const array = makePerspective();
2604
+ await TestRelationship.create(
2605
+ array,
2606
+ { label: "x", source: ["we://block/a"] as any },
2607
+ { batchId: "b" }
2608
+ );
2609
+
2610
+ expect(writtenTargets(scalar)).toEqual(writtenTargets(array));
2611
+ });
2612
+
2613
+ it("still writes the relation when there is no SHACL constructor", async () => {
2614
+ const perspective = makePerspective();
2615
+
2616
+ await TestNoConstructor.create(
2617
+ perspective,
2618
+ { node: "we://block/a" },
2619
+ { batchId: "batch-1" }
2620
+ );
2621
+
2622
+ expect(perspective.createSubject).not.toHaveBeenCalled();
2623
+ expect(writtenTargets(perspective)).toContain("we://block/a");
2624
+ });
2625
+ });
2626
+
2627
+ // The failure this closes: every `save()` of a new instance logged one
2628
+ // Rust-side "declares no setter" warning per ORM-internal field, per flag,
2629
+ // and per empty HasMany relation — none of which are real model data, so
2630
+ // none of them should ever have been offered to `createSubject` at all.
2631
+ describe("initialValues sent to createSubject", () => {
2632
+ @Model({ name: "TestNoisyPost" })
2633
+ class TestNoisyPost extends Ad4mModel {
2634
+ @Flag({ through: "test://post_type", value: "test://post" })
2635
+ type: string = "test://post";
2636
+
2637
+ @Property({ through: "test://title", required: true })
2638
+ title: string = "";
2639
+
2640
+ @HasMany({ through: "test://has_tag" })
2641
+ tags: string[] = [];
2642
+ }
2643
+
2644
+ it("excludes ORM bookkeeping fields, flags, and empty relations", async () => {
2645
+ const perspective = makePerspective();
2646
+
2647
+ await TestNoisyPost.create(perspective, { title: "hello" }, { batchId: "batch-1" });
2648
+
2649
+ expect(perspective.createSubject).toHaveBeenCalled();
2650
+ const initialValues = perspective.createSubject.mock.calls[0][2];
2651
+ expect(initialValues).toEqual({ title: "hello" });
2652
+ expect(initialValues).not.toHaveProperty("_baseExpression");
2653
+ expect(initialValues).not.toHaveProperty("_perspective");
2654
+ expect(initialValues).not.toHaveProperty("type");
2655
+ expect(initialValues).not.toHaveProperty("tags");
2656
+ });
2657
+ });
2658
+
2659
+ describe("generated @HasOne accessors", () => {
2660
+ it("forward batchId, so a to-one link can join a write group", async () => {
2661
+ // Without this the link commits on its own, so every subscriber sees the
2662
+ // record with its relation still empty — a card before its placement.
2663
+ const perspective = makePerspective();
2664
+ const rel = new TestRelationship(perspective, "we://rel/1") as any;
2665
+
2666
+ await rel.setSource("we://block/a", "batch-1");
2667
+ await rel.addTarget("we://block/b", "batch-1");
2668
+ await rel.removeTarget("we://block/b", "batch-1");
2669
+
2670
+ expect(batchIds(perspective)).toEqual(["batch-1", "batch-1", "batch-1"]);
2671
+ });
2672
+
2673
+ it("still work without one", async () => {
2674
+ const perspective = makePerspective();
2675
+ const rel = new TestRelationship(perspective, "we://rel/1") as any;
2676
+
2677
+ await rel.setSource("we://block/a");
2678
+
2679
+ expect(batchIds(perspective)).toEqual([undefined]);
2680
+ });
2681
+ });
2682
+ });
2683
+
2684
+ describe("Polymorphic relations", () => {
2685
+ @Model({ name: "PolyTextBlock" })
2686
+ class PolyTextBlock extends Ad4mModel {
2687
+ @Flag({ through: "we://flag", value: "we://text_block" })
2688
+ flag: string = "";
2689
+ @Property({ through: "we://text" })
2690
+ text: string = "";
2691
+ }
2692
+
2693
+ @Model({ name: "PolyImageBlock" })
2694
+ class PolyImageBlock extends Ad4mModel {
2695
+ @Flag({ through: "we://flag", value: "we://image_block" })
2696
+ flag: string = "";
2697
+ @Property({ through: "we://src" })
2698
+ src: string = "";
2699
+ }
2700
+
2701
+ @Model({ name: "PolyCollection" })
2702
+ class PolyCollection extends Ad4mModel {
2703
+ // No target class — the members are of genuinely different types, which is
2704
+ // the situation `polymorphic` exists for.
2705
+ @HasMany({
2706
+ through: "we://children",
2707
+ polymorphic: true,
2708
+ instantiateAs: () => [PolyTextBlock, PolyImageBlock],
2709
+ })
2710
+ children: string[] = [];
2711
+ }
2712
+
2713
+ const mockPerspective = { uuid: "test" } as any;
2714
+
2715
+ it("constructs each child as the class the executor says it is", () => {
2716
+ const raw = {
2717
+ instances: [
2718
+ {
2719
+ id: "we://c/1",
2720
+ children: [
2721
+ { id: "we://t/1", __subjectClass: "PolyTextBlock", text: "hello" },
2722
+ { id: "we://i/1", __subjectClass: "PolyImageBlock", src: "cat.png" },
2723
+ ],
2724
+ },
2725
+ ],
2726
+ };
2727
+
2728
+ const [collection] = PolyCollection.parseModelResult(mockPerspective, raw, {
2729
+ children: true,
2730
+ }) as any[];
2731
+
2732
+ expect(collection.children[0]).toBeInstanceOf(PolyTextBlock);
2733
+ expect(collection.children[1]).toBeInstanceOf(PolyImageBlock);
2734
+ // The property that only exists on the concrete class — what a base-class
2735
+ // hydration would have dropped before the value ever reached here.
2736
+ expect(collection.children[0].text).toBe("hello");
2737
+ expect(collection.children[1].src).toBe("cat.png");
2738
+ });
2739
+
2740
+ it("maps a child to its class by the name the class itself declares", () => {
2741
+ // The mapping is derived from `@Model({ name })`, not restated beside the
2742
+ // class list — the two cannot drift apart because there is only one of them.
2743
+ expect((PolyTextBlock as any).className).toBe("PolyTextBlock");
2744
+
2745
+ const raw = {
2746
+ instances: [
2747
+ {
2748
+ id: "we://c/1",
2749
+ children: [{ id: "we://t/1", __subjectClass: "PolyTextBlock", text: "hello" }],
2750
+ },
2751
+ ],
2752
+ };
2753
+
2754
+ const [collection] = PolyCollection.parseModelResult(mockPerspective, raw, {
2755
+ children: true,
2756
+ }) as any[];
2757
+
2758
+ expect(collection.children[0]).toBeInstanceOf(PolyTextBlock);
2759
+ });
2760
+
2761
+ it("carries the readings a child was chosen over onto the typed instance", () => {
2762
+ // A base expression can conform to two unrelated classes at once, and the
2763
+ // executor has to pick one to hydrate against. The set it picked from rides
2764
+ // back with the child, so a caller can see there was a choice — and fetch
2765
+ // the other reading by asking that class for this id.
2766
+ const raw = {
2767
+ instances: [
2768
+ {
2769
+ id: "we://c/1",
2770
+ children: [
2771
+ {
2772
+ id: "we://b/1",
2773
+ __subjectClass: "PolyTextBlock",
2774
+ __subjectClasses: ["PolyTextBlock", "PolyBookmark"],
2775
+ text: "hello",
2776
+ },
2777
+ ],
2778
+ },
2779
+ ],
2780
+ };
2781
+
2782
+ const [collection] = PolyCollection.parseModelResult(mockPerspective, raw, {
2783
+ children: true,
2784
+ }) as any[];
2785
+
2786
+ const child = collection.children[0];
2787
+ expect(child).toBeInstanceOf(PolyTextBlock);
2788
+ expect(child.__subjectClasses).toEqual(["PolyTextBlock", "PolyBookmark"]);
2789
+ });
2790
+
2791
+ it("leaves children as data when no instantiateAs is given", () => {
2792
+ @Model({ name: "PolyCollectionNoClasses" })
2793
+ class PolyCollectionNoClasses extends Ad4mModel {
2794
+ @HasMany({ through: "we://children", polymorphic: true })
2795
+ children: string[] = [];
2796
+ }
2797
+
2798
+ const raw = {
2799
+ instances: [
2800
+ {
2801
+ id: "we://c/1",
2802
+ children: [{ id: "we://t/1", __subjectClass: "PolyTextBlock", text: "hello" }],
2803
+ },
2804
+ ],
2805
+ };
2806
+
2807
+ const [collection] = PolyCollectionNoClasses.parseModelResult(mockPerspective, raw, {
2808
+ children: true,
2809
+ }) as any[];
2810
+
2811
+ // Still correct data, just untyped — the concrete class name is present for
2812
+ // a caller that wants to do its own dispatch.
2813
+ expect(collection.children[0].text).toBe("hello");
2814
+ expect(collection.children[0].__subjectClass).toBe("PolyTextBlock");
2815
+ });
2816
+
2817
+ it("keeps a child whose class is not listed, rather than dropping it", () => {
2818
+ // `instantiateAs` says what this call site can construct, not what the
2819
+ // relation may contain. A heterogeneous relation is open by definition, so
2820
+ // an unlisted class must arrive as data — narrowing a read to particular
2821
+ // classes is a thing to ask for in the query, never a side effect of
2822
+ // declaring which constructors happen to be in scope.
2823
+ const raw = {
2824
+ instances: [
2825
+ {
2826
+ id: "we://c/1",
2827
+ children: [
2828
+ { id: "we://t/1", __subjectClass: "PolyTextBlock", text: "hello" },
2829
+ { id: "we://k/1", __subjectClass: "PolyTaskBlock", done: true },
2830
+ ],
2831
+ },
2832
+ ],
2833
+ };
2834
+
2835
+ const [collection] = PolyCollection.parseModelResult(mockPerspective, raw, {
2836
+ children: true,
2837
+ }) as any[];
2838
+
2839
+ expect(collection.children).toHaveLength(2);
2840
+ expect(collection.children[0]).toBeInstanceOf(PolyTextBlock);
2841
+ expect(collection.children[1].done).toBe(true);
2842
+ expect(collection.children[1].__subjectClass).toBe("PolyTaskBlock");
2843
+ });
2844
+
2845
+ it("does not construct an unlisted child as the relation's declared target", () => {
2846
+ // A relation may declare a target *and* read polymorphically — the target
2847
+ // says what the members usually are, not what they must be. A child of some
2848
+ // third class was hydrated against its own shape, so building the declared
2849
+ // class over that JSON would answer `instanceof` for a class it is not,
2850
+ // carrying fields that class never declares.
2851
+ @Model({ name: "PolyBaseBlock" })
2852
+ class PolyBaseBlock extends Ad4mModel {
2853
+ @Property({ through: "we://base" })
2854
+ base: string = "";
2855
+ }
2856
+
2857
+ @Model({ name: "PolyTypedCollection" })
2858
+ class PolyTypedCollection extends Ad4mModel {
2859
+ @HasMany(() => PolyBaseBlock, {
2860
+ through: "we://children",
2861
+ polymorphic: true,
2862
+ instantiateAs: () => [PolyTextBlock],
2863
+ })
2864
+ children: any[] = [];
2865
+ }
2866
+
2867
+ const raw = {
2868
+ instances: [
2869
+ {
2870
+ id: "we://c/1",
2871
+ children: [
2872
+ { id: "we://k/1", __subjectClass: "PolyTaskBlock", done: true },
2873
+ { id: "we://b/1", __subjectClass: "PolyBaseBlock", base: "declared" },
2874
+ ],
2875
+ },
2876
+ ],
2877
+ };
2878
+
2879
+ const [collection] = PolyTypedCollection.parseModelResult(mockPerspective, raw, {
2880
+ children: true,
2881
+ }) as any[];
2882
+
2883
+ const [unlisted, declared] = collection.children;
2884
+ expect(unlisted).toBeDefined();
2885
+ expect(unlisted).not.toBeInstanceOf(PolyBaseBlock);
2886
+ expect(unlisted.done).toBe(true);
2887
+ expect(unlisted.__subjectClass).toBe("PolyTaskBlock");
2888
+ // The declared target is still right when it is the class the executor named.
2889
+ expect(declared).toBeInstanceOf(PolyBaseBlock);
2890
+ expect(declared.base).toBe("declared");
2891
+ });
2892
+
2893
+ it("does not use the declared target for another class when no classes are named", () => {
2894
+ // Naming no classes to build is not the same as authorising the declared
2895
+ // target to stand in for all of them. Without `instantiateAs` there is
2896
+ // simply nothing this side can construct for a class it was not told about.
2897
+ @Model({ name: "PolyBaseOnlyBlock" })
2898
+ class PolyBaseOnlyBlock extends Ad4mModel {
2899
+ @Property({ through: "we://base" })
2900
+ base: string = "";
2901
+ }
2902
+
2903
+ @Model({ name: "PolyTypedNoClasses" })
2904
+ class PolyTypedNoClasses extends Ad4mModel {
2905
+ @HasMany(() => PolyBaseOnlyBlock, { through: "we://children", polymorphic: true })
2906
+ children: any[] = [];
2907
+ }
2908
+
2909
+ const raw = {
2910
+ instances: [
2911
+ {
2912
+ id: "we://c/1",
2913
+ children: [
2914
+ { id: "we://k/1", __subjectClass: "PolyTaskBlock", done: true },
2915
+ { id: "we://b/1", __subjectClass: "PolyBaseOnlyBlock", base: "declared" },
2916
+ ],
2917
+ },
2918
+ ],
2919
+ };
2920
+
2921
+ const [collection] = PolyTypedNoClasses.parseModelResult(mockPerspective, raw, {
2922
+ children: true,
2923
+ }) as any[];
2924
+
2925
+ const [unlisted, declared] = collection.children;
2926
+ expect(unlisted).not.toBeInstanceOf(PolyBaseOnlyBlock);
2927
+ expect(unlisted.done).toBe(true);
2928
+ expect(unlisted.__subjectClass).toBe("PolyTaskBlock");
2929
+ expect(declared).toBeInstanceOf(PolyBaseOnlyBlock);
2930
+ expect(declared.base).toBe("declared");
2931
+ });
2932
+
2933
+ it("calls instantiateAs late, so a circular import can still resolve", () => {
2934
+ let defined = false;
2935
+ @Model({ name: "PolyLateCollection" })
2936
+ class PolyLateCollection extends Ad4mModel {
2937
+ // Evaluated at decoration time this would throw, the way an array literal
2938
+ // naming a class from further round an import cycle would.
2939
+ @HasMany({
2940
+ through: "we://children",
2941
+ polymorphic: true,
2942
+ instantiateAs: () => {
2943
+ if (!defined) throw new ReferenceError("class not defined yet");
2944
+ return [PolyTextBlock];
2945
+ },
2946
+ })
2947
+ children: string[] = [];
2948
+ }
2949
+
2950
+ defined = true;
2951
+ const raw = {
2952
+ instances: [
2953
+ {
2954
+ id: "we://c/1",
2955
+ children: [{ id: "we://t/1", __subjectClass: "PolyTextBlock", text: "hello" }],
2956
+ },
2957
+ ],
2958
+ };
2959
+
2960
+ const [collection] = PolyLateCollection.parseModelResult(mockPerspective, raw, {
2961
+ children: true,
2962
+ }) as any[];
2963
+
2964
+ expect(collection.children[0]).toBeInstanceOf(PolyTextBlock);
2965
+ });
2966
+
2967
+ it("asks the executor for polymorphic hydration without the caller repeating it", () => {
2968
+ // The relation being heterogeneous is a fact about the data, so declaring it
2969
+ // on the model should be enough — `include: { children: true }` must still
2970
+ // arrive at the executor as a polymorphic read.
2971
+ const { queryJson } = (PolyCollection as any).prepareModelQueryParams({
2972
+ include: { children: true },
2973
+ });
2974
+
2975
+ expect(JSON.parse(queryJson).include.children).toEqual({
2976
+ polymorphic: true,
2977
+ preferClasses: ["PolyTextBlock", "PolyImageBlock"],
2978
+ });
2979
+ });
2980
+
2981
+ it("sends the classes it can build as the classes it wants, in declaration order", () => {
2982
+ // The two questions have one answer: what this call site can construct is
2983
+ // what it wants its targets read as. Sent with the query rather than applied
2984
+ // to the results, so the same request gives the same reading to anyone.
2985
+ const { queryJson } = (PolyCollection as any).prepareModelQueryParams({
2986
+ include: { children: true },
2987
+ });
2988
+
2989
+ // Declaration order is the preference order — a target conforming to two of
2990
+ // them is read as whichever was named first.
2991
+ expect(JSON.parse(queryJson).include.children.preferClasses).toEqual([
2992
+ "PolyTextBlock",
2993
+ "PolyImageBlock",
2994
+ ]);
2995
+ });
2996
+
2997
+ it("lets an explicit preference at the call site win over the declaration", () => {
2998
+ const { queryJson } = (PolyCollection as any).prepareModelQueryParams({
2999
+ include: { children: { preferClasses: ["PolyBookmark"] } },
3000
+ });
3001
+
3002
+ expect(JSON.parse(queryJson).include.children.preferClasses).toEqual(["PolyBookmark"]);
3003
+ });
3004
+
3005
+ it("sends no preference for a polymorphic relation that names no classes", () => {
3006
+ @Model({ name: "PolyCollectionUndeclared" })
3007
+ class PolyCollectionUndeclared extends Ad4mModel {
3008
+ @HasMany({ through: "we://children", polymorphic: true })
3009
+ children: string[] = [];
3010
+ }
3011
+
3012
+ const { queryJson } = (PolyCollectionUndeclared as any).prepareModelQueryParams({
3013
+ include: { children: true },
3014
+ });
3015
+
3016
+ // Nothing to prefer, so nothing is sent and the executor ranks by
3017
+ // specificity exactly as it did before any of this existed.
3018
+ expect(JSON.parse(queryJson).include.children).toEqual({ polymorphic: true });
3019
+ });
3020
+
3021
+ it("lets an explicit false at the call site win", () => {
3022
+ const { queryJson } = (PolyCollection as any).prepareModelQueryParams({
3023
+ include: { children: { polymorphic: false } },
3024
+ });
3025
+
3026
+ expect(JSON.parse(queryJson).include.children.polymorphic).toBe(false);
3027
+ });
3028
+
3029
+ it("applies the default at every depth of a nested include", () => {
3030
+ // `sections` is a plain typed relation, so the nested `children` is read off
3031
+ // PolyCollection rather than off the class being queried. Left to the top
3032
+ // level, the default would never reach it and the include would arrive at
3033
+ // the executor with no shape to resolve — the query fails outright.
3034
+ @Model({ name: "PolyPage" })
3035
+ class PolyPage extends Ad4mModel {
3036
+ @HasMany(() => PolyCollection, { through: "we://sections" })
3037
+ sections: any[] = [];
3038
+ }
3039
+
3040
+ const { queryJson } = (PolyPage as any).prepareModelQueryParams({
3041
+ include: { sections: { include: { children: true } } },
3042
+ });
3043
+
3044
+ const include = JSON.parse(queryJson).include;
3045
+ expect(include.sections.include.children).toEqual({
3046
+ polymorphic: true,
3047
+ preferClasses: ["PolyTextBlock", "PolyImageBlock"],
3048
+ });
3049
+ });
3050
+
3051
+ it("lets an explicit false win at depth too", () => {
3052
+ @Model({ name: "PolyPageExplicit" })
3053
+ class PolyPageExplicit extends Ad4mModel {
3054
+ @HasMany(() => PolyCollection, { through: "we://sections" })
3055
+ sections: any[] = [];
3056
+ }
3057
+
3058
+ const { queryJson } = (PolyPageExplicit as any).prepareModelQueryParams({
3059
+ include: { sections: { include: { children: { polymorphic: false } } } },
3060
+ });
3061
+
3062
+ expect(JSON.parse(queryJson).include.sections.include.children.polymorphic).toBe(false);
3063
+ });
3064
+ });
3065
+
3066
+ describe("Ordered relations", () => {
3067
+ @Model({ name: "OrderedColumn" })
3068
+ class OrderedColumn extends Ad4mModel {
3069
+ @HasMany({ through: "kanban://has_task", ordering: { strategy: "linkedList" } })
3070
+ tasks: string[] = [];
3071
+
3072
+ @HasMany({ through: "kanban://archived" })
3073
+ archived: string[] = [];
3074
+ }
3075
+
3076
+ const mockPerspective = { uuid: "test" } as any;
3077
+
3078
+ it("declares its ordering in SHACL", () => {
3079
+ const { shape } = (OrderedColumn as any).generateSHACL();
3080
+ const tasks = shape.properties.find((p: any) => p.name === "tasks");
3081
+ expect(tasks.ordering).toBe("linkedList");
3082
+ });
3083
+
3084
+ it("declares the predicate the ordering entries are stored under", () => {
3085
+ // Entries live on the parent under one shared predicate. The instance query
3086
+ // builds its predicate filter from the shape's declared paths, so without
3087
+ // this the read that needs the ordering links filters them out.
3088
+ const { shape } = (OrderedColumn as any).generateSHACL();
3089
+ const orderProp = shape.properties.find(
3090
+ (p: any) => p.path === "ad4m://collection_order"
3091
+ );
3092
+ expect(orderProp).toBeDefined();
3093
+ });
3094
+
3095
+ it("omits that predicate when nothing on the class is ordered", () => {
3096
+ @Model({ name: "UnorderedOnly" })
3097
+ class UnorderedOnly extends Ad4mModel {
3098
+ @HasMany({ through: "kanban://archived" })
3099
+ archived: string[] = [];
3100
+ }
3101
+ const { shape } = (UnorderedOnly as any).generateSHACL();
3102
+ expect(
3103
+ shape.properties.find((p: any) => p.path === "ad4m://collection_order")
3104
+ ).toBeUndefined();
3105
+ });
3106
+
3107
+ it("treats a reorder as a change", () => {
3108
+ // The whole point: for an ordered relation the sequence *is* the state, so
3109
+ // sorting before comparing would make save() a no-op for the one edit this
3110
+ // feature exists to support.
3111
+ const column = new OrderedColumn(mockPerspective, "kanban://col/1") as any;
3112
+ column.tasks = ["a", "b", "c"];
3113
+ column.takeSnapshot();
3114
+
3115
+ column.tasks = ["c", "a", "b"];
3116
+ expect(column.changedFields()).toContain("tasks");
3117
+ });
3118
+
3119
+ it("still treats a reorder of an unordered relation as no change", () => {
3120
+ // An unordered relation is a set — the executor returns it by link
3121
+ // timestamp, so assigning the same members in another order changed nothing.
3122
+ const column = new OrderedColumn(mockPerspective, "kanban://col/1") as any;
3123
+ column.archived = ["a", "b", "c"];
3124
+ column.takeSnapshot();
3125
+
3126
+ column.archived = ["c", "a", "b"];
3127
+ expect(column.changedFields()).not.toContain("archived");
3128
+ });
3129
+
3130
+ it("round-trips ordering through SHACL links", () => {
3131
+ const { shape } = (OrderedColumn as any).generateSHACL();
3132
+ const links = shape.toLinks().map((l: any) => ({
3133
+ source: l.source,
3134
+ predicate: l.predicate,
3135
+ target: l.target,
3136
+ }));
3137
+ const reconstructed = SHACLShape.fromLinks(links as any, shape.nodeShapeUri);
3138
+ const tasks = reconstructed.properties.find((p: any) => p.name === "tasks");
3139
+ expect(tasks!.ordering).toBe("linkedList");
3140
+ });
3141
+ });