@coasys/ad4m 0.13.0-test-7 → 0.13.0-test-8

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 (264) hide show
  1. package/lib/index.cjs +1109 -828
  2. package/lib/index.js +1096 -828
  3. package/lib/src/Ad4mClient.d.ts +4 -1
  4. package/lib/src/Ad4mClient.js +2 -2
  5. package/lib/src/agent/AgentClient.js +17 -0
  6. package/lib/src/ai/AIClient.js +1 -1
  7. package/lib/src/apiClient.d.ts +5 -1
  8. package/lib/src/apiClient.js +14 -6
  9. package/lib/src/generated/rest/AIModelLoadingStatus.d.ts +7 -0
  10. package/lib/src/generated/rest/AIModelLoadingStatus.js +2 -0
  11. package/lib/src/generated/rest/AddAgentInfosRequest.d.ts +3 -0
  12. package/lib/src/generated/rest/AddAgentInfosRequest.js +2 -0
  13. package/lib/src/generated/rest/AddLinkExpressionRequest.d.ts +6 -0
  14. package/lib/src/generated/rest/AddLinkExpressionRequest.js +1 -0
  15. package/lib/src/generated/rest/AddLinkRequest.d.ts +6 -0
  16. package/lib/src/generated/rest/AddLinkRequest.js +1 -0
  17. package/lib/src/generated/rest/AddLinksBulkRequest.d.ts +6 -0
  18. package/lib/src/generated/rest/AddLinksBulkRequest.js +1 -0
  19. package/lib/src/generated/rest/AddSdnaRequest.d.ts +6 -0
  20. package/lib/src/generated/rest/AddSdnaRequest.js +2 -0
  21. package/lib/src/generated/rest/ApplyTemplateRequest.d.ts +4 -0
  22. package/lib/src/generated/rest/ApplyTemplateRequest.js +2 -0
  23. package/lib/src/generated/rest/AuthInfoInput.d.ts +10 -0
  24. package/lib/src/generated/rest/AuthInfoInput.js +1 -0
  25. package/lib/src/generated/rest/BroadcastRequest.d.ts +6 -0
  26. package/lib/src/generated/rest/BroadcastRequest.js +1 -0
  27. package/lib/src/generated/rest/CapabilityInput.d.ts +5 -0
  28. package/lib/src/generated/rest/CapabilityInput.js +1 -0
  29. package/lib/src/generated/rest/CommitBatchRequest.d.ts +3 -0
  30. package/lib/src/generated/rest/CommitBatchRequest.js +2 -0
  31. package/lib/src/generated/rest/ComputeLogEntry.d.ts +9 -0
  32. package/lib/src/generated/rest/ComputeLogEntry.js +2 -0
  33. package/lib/src/generated/rest/CreateExpressionRequest.d.ts +4 -0
  34. package/lib/src/generated/rest/CreateExpressionRequest.js +2 -0
  35. package/lib/src/generated/rest/CreatePerspectiveRequest.d.ts +3 -0
  36. package/lib/src/generated/rest/CreatePerspectiveRequest.js +2 -0
  37. package/lib/src/generated/rest/CreateSubjectRequest.d.ts +6 -0
  38. package/lib/src/generated/rest/CreateSubjectRequest.js +2 -0
  39. package/lib/src/generated/rest/CreateUserRequest.d.ts +4 -0
  40. package/lib/src/generated/rest/CreateUserRequest.js +2 -0
  41. package/lib/src/generated/rest/CreateUserResponse.d.ts +5 -0
  42. package/lib/src/generated/rest/CreateUserResponse.js +2 -0
  43. package/lib/src/generated/rest/DecoratedExpressionProof.d.ts +6 -0
  44. package/lib/src/generated/rest/DecoratedExpressionProof.js +2 -0
  45. package/lib/src/generated/rest/DecoratedLinkExpression.d.ts +10 -0
  46. package/lib/src/generated/rest/DecoratedLinkExpression.js +1 -0
  47. package/lib/src/generated/rest/DisposeQueryRequest.d.ts +3 -0
  48. package/lib/src/generated/rest/DisposeQueryRequest.js +2 -0
  49. package/lib/src/generated/rest/EmailTestRequest.d.ts +6 -0
  50. package/lib/src/generated/rest/EmailTestRequest.js +2 -0
  51. package/lib/src/generated/rest/EmbedRequest.d.ts +4 -0
  52. package/lib/src/generated/rest/EmbedRequest.js +2 -0
  53. package/lib/src/generated/rest/EntanglementProofInput.d.ts +6 -0
  54. package/lib/src/generated/rest/EntanglementProofInput.js +2 -0
  55. package/lib/src/generated/rest/EntanglementProofPreflightRequest.d.ts +4 -0
  56. package/lib/src/generated/rest/EntanglementProofPreflightRequest.js +2 -0
  57. package/lib/src/generated/rest/ExecuteCommandsRequest.d.ts +4 -0
  58. package/lib/src/generated/rest/ExecuteCommandsRequest.js +2 -0
  59. package/lib/src/generated/rest/ExportRequest.d.ts +5 -0
  60. package/lib/src/generated/rest/ExportRequest.js +2 -0
  61. package/lib/src/generated/rest/ExpressionManyRequest.d.ts +3 -0
  62. package/lib/src/generated/rest/ExpressionManyRequest.js +2 -0
  63. package/lib/src/generated/rest/ExpressionProof.d.ts +4 -0
  64. package/lib/src/generated/rest/ExpressionProof.js +2 -0
  65. package/lib/src/generated/rest/ExpressionProofInput.d.ts +6 -0
  66. package/lib/src/generated/rest/ExpressionProofInput.js +2 -0
  67. package/lib/src/generated/rest/FriendSendMessageRequest.d.ts +3 -0
  68. package/lib/src/generated/rest/FriendSendMessageRequest.js +2 -0
  69. package/lib/src/generated/rest/FriendsListRequest.d.ts +3 -0
  70. package/lib/src/generated/rest/FriendsListRequest.js +2 -0
  71. package/lib/src/generated/rest/GenerateAgentRequest.d.ts +3 -0
  72. package/lib/src/generated/rest/GenerateAgentRequest.js +2 -0
  73. package/lib/src/generated/rest/GenerateJwtRequest.d.ts +4 -0
  74. package/lib/src/generated/rest/GenerateJwtRequest.js +2 -0
  75. package/lib/src/generated/rest/GetSubjectDataRequest.d.ts +4 -0
  76. package/lib/src/generated/rest/GetSubjectDataRequest.js +2 -0
  77. package/lib/src/generated/rest/HostingInfoResponse.d.ts +5 -0
  78. package/lib/src/generated/rest/HostingInfoResponse.js +2 -0
  79. package/lib/src/generated/rest/HostingWalletResponse.d.ts +4 -0
  80. package/lib/src/generated/rest/HostingWalletResponse.js +2 -0
  81. package/lib/src/generated/rest/ImportAgentRequest.d.ts +6 -0
  82. package/lib/src/generated/rest/ImportAgentRequest.js +2 -0
  83. package/lib/src/generated/rest/ImportRequest.d.ts +4 -0
  84. package/lib/src/generated/rest/ImportRequest.js +2 -0
  85. package/lib/src/generated/rest/JoinNeighbourhoodRequest.d.ts +3 -0
  86. package/lib/src/generated/rest/JoinNeighbourhoodRequest.js +2 -0
  87. package/lib/src/generated/rest/KeepAliveQueryRequest.d.ts +3 -0
  88. package/lib/src/generated/rest/KeepAliveQueryRequest.js +2 -0
  89. package/lib/src/generated/rest/LanguageMetaInput.d.ts +6 -0
  90. package/lib/src/generated/rest/LanguageMetaInput.js +2 -0
  91. package/lib/src/generated/rest/Link.d.ts +5 -0
  92. package/lib/src/generated/rest/Link.js +2 -0
  93. package/lib/src/generated/rest/LinkExpression.d.ts +10 -0
  94. package/lib/src/generated/rest/LinkExpression.js +1 -0
  95. package/lib/src/generated/rest/LinkExpressionInput.d.ts +10 -0
  96. package/lib/src/generated/rest/LinkExpressionInput.js +1 -0
  97. package/lib/src/generated/rest/LinkInput.d.ts +5 -0
  98. package/lib/src/generated/rest/LinkInput.js +2 -0
  99. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.d.ts +3 -0
  100. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.js +2 -0
  101. package/lib/src/generated/rest/LinkMutationRequest.d.ts +12 -0
  102. package/lib/src/generated/rest/LinkMutationRequest.js +1 -0
  103. package/lib/src/generated/rest/LinkMutationResponse.d.ts +9 -0
  104. package/lib/src/generated/rest/LinkMutationResponse.js +1 -0
  105. package/lib/src/generated/rest/LinkMutations.d.ts +6 -0
  106. package/lib/src/generated/rest/LinkMutations.js +1 -0
  107. package/lib/src/generated/rest/LinkMutationsRequest.d.ts +5 -0
  108. package/lib/src/generated/rest/LinkMutationsRequest.js +1 -0
  109. package/lib/src/generated/rest/LinkStatus.d.ts +1 -0
  110. package/lib/src/generated/rest/LinkStatus.js +2 -0
  111. package/lib/src/generated/rest/LinkUpdateInput.d.ts +5 -0
  112. package/lib/src/generated/rest/LinkUpdateInput.js +1 -0
  113. package/lib/src/generated/rest/LockAgentRequest.d.ts +3 -0
  114. package/lib/src/generated/rest/LockAgentRequest.js +2 -0
  115. package/lib/src/generated/rest/LoginUserRequest.d.ts +5 -0
  116. package/lib/src/generated/rest/LoginUserRequest.js +2 -0
  117. package/lib/src/generated/rest/ModelType.d.ts +1 -0
  118. package/lib/src/generated/rest/ModelType.js +2 -0
  119. package/lib/src/generated/rest/NotificationGrantRequest.d.ts +3 -0
  120. package/lib/src/generated/rest/NotificationGrantRequest.js +2 -0
  121. package/lib/src/generated/rest/NotificationInput.d.ts +10 -0
  122. package/lib/src/generated/rest/NotificationInput.js +2 -0
  123. package/lib/src/generated/rest/OpenLinkRequest.d.ts +3 -0
  124. package/lib/src/generated/rest/OpenLinkRequest.js +2 -0
  125. package/lib/src/generated/rest/PermitCapabilityRequest.d.ts +3 -0
  126. package/lib/src/generated/rest/PermitCapabilityRequest.js +2 -0
  127. package/lib/src/generated/rest/PerspectiveInput.d.ts +4 -0
  128. package/lib/src/generated/rest/PerspectiveInput.js +1 -0
  129. package/lib/src/generated/rest/PromptRequest.d.ts +4 -0
  130. package/lib/src/generated/rest/PromptRequest.js +2 -0
  131. package/lib/src/generated/rest/PublicPerspectiveInput.d.ts +4 -0
  132. package/lib/src/generated/rest/PublicPerspectiveInput.js +1 -0
  133. package/lib/src/generated/rest/PublishLanguageRequest.d.ts +5 -0
  134. package/lib/src/generated/rest/PublishLanguageRequest.js +1 -0
  135. package/lib/src/generated/rest/PublishNeighbourhoodRequest.d.ts +6 -0
  136. package/lib/src/generated/rest/PublishNeighbourhoodRequest.js +1 -0
  137. package/lib/src/generated/rest/QueryRequest.d.ts +7 -0
  138. package/lib/src/generated/rest/QueryRequest.js +2 -0
  139. package/lib/src/generated/rest/RemoveLinkRequest.d.ts +5 -0
  140. package/lib/src/generated/rest/RemoveLinkRequest.js +1 -0
  141. package/lib/src/generated/rest/RemoveLinksBulkRequest.d.ts +5 -0
  142. package/lib/src/generated/rest/RemoveLinksBulkRequest.js +1 -0
  143. package/lib/src/generated/rest/RequestCapabilityRequest.d.ts +4 -0
  144. package/lib/src/generated/rest/RequestCapabilityRequest.js +1 -0
  145. package/lib/src/generated/rest/RequestPaymentRequest.d.ts +3 -0
  146. package/lib/src/generated/rest/RequestPaymentRequest.js +2 -0
  147. package/lib/src/generated/rest/RequestVerificationRequest.d.ts +4 -0
  148. package/lib/src/generated/rest/RequestVerificationRequest.js +2 -0
  149. package/lib/src/generated/rest/ResourceInput.d.ts +4 -0
  150. package/lib/src/generated/rest/ResourceInput.js +2 -0
  151. package/lib/src/generated/rest/SetDefaultModelRequest.d.ts +4 -0
  152. package/lib/src/generated/rest/SetDefaultModelRequest.js +1 -0
  153. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.d.ts +3 -0
  154. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.js +2 -0
  155. package/lib/src/generated/rest/SetHotWalletAddressRequest.d.ts +3 -0
  156. package/lib/src/generated/rest/SetHotWalletAddressRequest.js +2 -0
  157. package/lib/src/generated/rest/SetMultiUserRequest.d.ts +3 -0
  158. package/lib/src/generated/rest/SetMultiUserRequest.js +2 -0
  159. package/lib/src/generated/rest/SetOnlineStatusRequest.d.ts +5 -0
  160. package/lib/src/generated/rest/SetOnlineStatusRequest.js +1 -0
  161. package/lib/src/generated/rest/SetStatusRequest.d.ts +3 -0
  162. package/lib/src/generated/rest/SetStatusRequest.js +2 -0
  163. package/lib/src/generated/rest/SetUserFreeAccessRequest.d.ts +4 -0
  164. package/lib/src/generated/rest/SetUserFreeAccessRequest.js +2 -0
  165. package/lib/src/generated/rest/SignMessageRequest.d.ts +3 -0
  166. package/lib/src/generated/rest/SignMessageRequest.js +2 -0
  167. package/lib/src/generated/rest/SignalRequest.d.ts +6 -0
  168. package/lib/src/generated/rest/SignalRequest.js +1 -0
  169. package/lib/src/generated/rest/SubscribeQueryRequest.d.ts +3 -0
  170. package/lib/src/generated/rest/SubscribeQueryRequest.js +2 -0
  171. package/lib/src/generated/rest/SubscribeQueryResponse.d.ts +4 -0
  172. package/lib/src/generated/rest/SubscribeQueryResponse.js +2 -0
  173. package/lib/src/generated/rest/TrustedAgentsRequest.d.ts +3 -0
  174. package/lib/src/generated/rest/TrustedAgentsRequest.js +2 -0
  175. package/lib/src/generated/rest/UnlockAgentRequest.d.ts +4 -0
  176. package/lib/src/generated/rest/UnlockAgentRequest.js +2 -0
  177. package/lib/src/generated/rest/UpdateLinkRequest.d.ts +7 -0
  178. package/lib/src/generated/rest/UpdateLinkRequest.js +1 -0
  179. package/lib/src/generated/rest/UpdatePerspectiveRequest.d.ts +3 -0
  180. package/lib/src/generated/rest/UpdatePerspectiveRequest.js +2 -0
  181. package/lib/src/generated/rest/UpdateProfileRequest.d.ts +5 -0
  182. package/lib/src/generated/rest/UpdateProfileRequest.js +1 -0
  183. package/lib/src/generated/rest/UserStatistics.d.ts +9 -0
  184. package/lib/src/generated/rest/UserStatistics.js +2 -0
  185. package/lib/src/generated/rest/VerificationRequestResult.d.ts +6 -0
  186. package/lib/src/generated/rest/VerificationRequestResult.js +2 -0
  187. package/lib/src/generated/rest/VerifyEmailRequest.d.ts +6 -0
  188. package/lib/src/generated/rest/VerifyEmailRequest.js +2 -0
  189. package/lib/src/generated/rest/VerifySignatureRequest.d.ts +5 -0
  190. package/lib/src/generated/rest/VerifySignatureRequest.js +2 -0
  191. package/lib/src/generated/rest/WriteSettingsRequest.d.ts +3 -0
  192. package/lib/src/generated/rest/WriteSettingsRequest.js +2 -0
  193. package/lib/src/generated/rest/index.d.ts +73 -0
  194. package/lib/src/generated/rest/index.js +8 -0
  195. package/lib/src/generated/rest/routes.d.ts +587 -0
  196. package/lib/src/generated/rest/routes.js +3 -0
  197. package/lib/src/index.d.ts +4 -0
  198. package/lib/src/index.js +4 -0
  199. package/lib/src/model/Ad4mModel.d.ts +30 -36
  200. package/lib/src/model/Ad4mModel.js +93 -382
  201. package/lib/src/model/Ad4mModel.test.js +735 -480
  202. package/lib/src/model/ModelQueryBuilder.d.ts +5 -10
  203. package/lib/src/model/ModelQueryBuilder.js +142 -62
  204. package/lib/src/model/decorators.d.ts +7 -4
  205. package/lib/src/model/decorators.js +0 -7
  206. package/lib/src/model/query-sparql.d.ts +0 -10
  207. package/lib/src/model/query-sparql.js +10 -15
  208. package/lib/src/model/query-sparql.test.js +10 -92
  209. package/lib/src/model/query-surreal.d.ts +44 -0
  210. package/lib/src/model/query-surreal.js +249 -0
  211. package/lib/src/model/shacl-gen.js +120 -47
  212. package/lib/src/model/surreal-utils.d.ts +42 -0
  213. package/lib/src/model/surreal-utils.js +128 -0
  214. package/lib/src/model/types.d.ts +140 -4
  215. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +33 -33
  216. package/lib/src/perspectives/PerspectiveClient.d.ts +13 -4
  217. package/lib/src/perspectives/PerspectiveClient.js +22 -6
  218. package/lib/src/perspectives/PerspectiveProxy.d.ts +27 -7
  219. package/lib/src/perspectives/PerspectiveProxy.js +60 -12
  220. package/lib/src/perspectives/PerspectiveProxy.test.d.ts +1 -0
  221. package/lib/src/perspectives/PerspectiveProxy.test.js +34 -0
  222. package/lib/src/perspectives/SparqlBindings.d.ts +47 -0
  223. package/lib/src/perspectives/SparqlBindings.js +65 -0
  224. package/lib/src/perspectives/WakerSubscriptionManager.js +5 -4
  225. package/lib/src/restClient.d.ts +52 -0
  226. package/lib/src/restClient.js +227 -0
  227. package/lib/src/shacl/NodeExpression.d.ts +44 -0
  228. package/lib/src/shacl/NodeExpression.js +39 -0
  229. package/lib/src/shacl/SHACLShape.d.ts +23 -0
  230. package/lib/src/shacl/SHACLShape.js +115 -1
  231. package/lib/src/shacl/SHACLShape.test.js +0 -82
  232. package/lib/src/shacl/builders.d.ts +58 -0
  233. package/lib/src/shacl/builders.js +76 -0
  234. package/lib/src/shacl/index.d.ts +36 -0
  235. package/lib/src/shacl/index.js +33 -0
  236. package/package.json +11 -8
  237. package/src/Ad4mClient.ts +7 -2
  238. package/src/agent/AgentClient.ts +23 -0
  239. package/src/ai/AIClient.ts +1 -1
  240. package/src/apiClient.ts +17 -6
  241. package/src/index.ts +4 -0
  242. package/src/model/Ad4mModel.test.ts +274 -72
  243. package/src/model/Ad4mModel.ts +140 -420
  244. package/src/model/ModelQueryBuilder.ts +136 -71
  245. package/src/model/decorators.ts +7 -13
  246. package/src/model/query-sparql.test.ts +35 -19
  247. package/src/model/query-sparql.ts +10 -16
  248. package/src/model/relation-filtering.test.ts +46 -39
  249. package/src/model/shacl-gen.ts +128 -54
  250. package/src/model/shacl-roundtrip.test.ts +197 -0
  251. package/src/model/types-typed-query.test.ts +360 -0
  252. package/src/model/types.ts +196 -4
  253. package/src/perspectives/PerspectiveClient.ts +24 -8
  254. package/src/perspectives/PerspectiveProxy.test.ts +85 -1
  255. package/src/perspectives/PerspectiveProxy.ts +65 -20
  256. package/src/perspectives/SparqlBindings.ts +79 -0
  257. package/src/perspectives/WakerSubscriptionManager.ts +5 -4
  258. package/src/shacl/NodeExpression.ts +54 -0
  259. package/src/shacl/SHACLShape.test.ts +172 -0
  260. package/src/shacl/SHACLShape.ts +173 -1
  261. package/src/shacl/builders.ts +86 -0
  262. package/src/shacl/index.ts +72 -0
  263. package/lib/src/model/model-manifest.d.ts +0 -41
  264. package/lib/src/model/model-manifest.js +0 -11
@@ -3,7 +3,7 @@ import { Link } from "../links/Links";
3
3
  import { LinkQuery } from "../perspectives/LinkQuery";
4
4
  import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
5
5
  import { makeRandomId } from "./util";
6
- import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
6
+ import { getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
7
7
  import type { PropertyOptions, PropertyMetadataEntry, RelationMetadataEntry } from "./decorators";
8
8
  import { formatQueryValue, compileWhereClause } from "./query-utils";
9
9
  import { resolveParentPredicate } from "./query-common";
@@ -21,101 +21,15 @@ import type {
21
21
  GetOptions, AllInstancesResult, ResultsWithTotalCount,
22
22
  PaginationResult, PropertyMetadata, RelationMetadata, ModelMetadata,
23
23
  IncludeProjection,
24
+ TypedQuery, IncludeExtras, IncludeOf,
24
25
  } from "./types";
25
26
 
26
27
 
27
- // ---------------------------------------------------------------------------
28
- // Default decoder for file-storage (non-literal resolveLanguage) properties
29
- // ---------------------------------------------------------------------------
30
-
31
- /**
32
- * When the Rust executor resolves a non-literal expression it may return a
33
- * `FileData`-shaped object (`{ data_base64, file_type, ... }`) rather than a
34
- * raw URI string. If the model class has no custom `transform` registered
35
- * (e.g. it was synthesised from a SHACL shape at runtime) we still want to
36
- * decode the content rather than passing raw `FileData` to callers.
37
- *
38
- * Decoding rules (mirrors the JS `decodeFileAsJson` / `decodeFileAsString` helpers):
39
- * - `application/json` (default when `file_type` is absent) → JSON.parse
40
- * - anything else → raw decoded string
41
- *
42
- * If `resolved` is not a `FileData` object the value is returned unchanged so
43
- * that callers can use this as a safe unconditional fallback.
44
- */
45
- function defaultFileDecode(resolved: unknown): unknown {
46
- if (
47
- resolved !== null &&
48
- typeof resolved === 'object' &&
49
- 'data_base64' in (resolved as object)
50
- ) {
51
- const fd = resolved as { data_base64: string; file_type?: string };
52
- let raw: string;
53
- try {
54
- raw = atob(fd.data_base64);
55
- } catch {
56
- return resolved; // malformed base64 — keep as-is
57
- }
58
- const isJson = !fd.file_type || fd.file_type === 'application/json';
59
- if (isJson) {
60
- try { return JSON.parse(raw); } catch { return raw; }
61
- }
62
- return raw;
63
- }
64
- return resolved;
65
- }
66
28
 
67
29
  // ---------------------------------------------------------------------------
68
30
  // Helpers for Rust-side include resolution
69
31
  // ---------------------------------------------------------------------------
70
32
 
71
- /**
72
- * Recursively enrich relation metadata in the shape with target class shapes
73
- * so the Rust endpoint can resolve includes in-process (no extra GraphQL
74
- * round-trips per relation).
75
- */
76
- function enrichShapeForIncludes(
77
- metadata: ModelMetadata,
78
- include: IncludeMap,
79
- allRelMeta: Record<string, RelationMetadataEntry>,
80
- ): void {
81
- for (const [relName, includeVal] of Object.entries(include)) {
82
- if (!includeVal) continue;
83
- const meta = allRelMeta[relName];
84
- if (!meta?.target) continue;
85
-
86
- const TargetClass = meta.target() as typeof Ad4mModel;
87
- // Deep-copy so we don't mutate the cached metadata
88
- const targetMeta = JSON.parse(JSON.stringify(TargetClass.getModelMetadata()));
89
-
90
- // Ensure the relation is in metadata.relations (fallback for edge cases)
91
- if (!metadata.relations[relName]) {
92
- metadata.relations[relName] = {
93
- name: relName,
94
- predicate: meta.predicate,
95
- direction:
96
- meta.kind === 'belongsToMany' || meta.kind === 'belongsToOne'
97
- ? 'reverse'
98
- : 'forward',
99
- };
100
- }
101
- const rel = metadata.relations[relName] as any;
102
- rel.kind = meta.kind;
103
- rel.maxCount = meta.maxCount;
104
- rel.targetShape = targetMeta;
105
- rel.targetClassName = targetMeta.className;
106
-
107
- // Recurse for nested includes
108
- const nested =
109
- typeof includeVal === 'object' && includeVal !== null
110
- ? (includeVal as any).include
111
- : undefined;
112
- if (nested) {
113
- const targetRelMeta = getRelationsMetadata(TargetClass as any);
114
- enrichShapeForIncludes(targetMeta, nested, targetRelMeta);
115
- }
116
- }
117
- }
118
-
119
33
  /**
120
34
  * Construct a model class instance from a plain JSON object returned by the
121
35
  * Rust endpoint. Recursively converts included relation values (which come
@@ -166,19 +80,6 @@ function jsonToModelInstance<T extends Ad4mModel>(
166
80
  instance[key] = value;
167
81
  }
168
82
 
169
- // Apply property transform functions from decorators (only for literal-resolved
170
- // or no-resolveLanguage properties; non-literal properties are resolved + transformed
171
- // asynchronously in executeModelQuery).
172
- try {
173
- const propsMeta = getPropertiesMetadata(ModelClass as any);
174
- for (const [propName, opts] of Object.entries(propsMeta)) {
175
- const o = opts as any;
176
- if (typeof o.transform !== 'function' || !(propName in json)) continue;
177
- // Skip non-literal resolveLanguage props — they need async expression resolution first
178
- if (o.resolveLanguage != null && o.resolveLanguage !== 'literal') continue;
179
- instance[propName] = o.transform(instance[propName]);
180
- }
181
- } catch (_) { /* no metadata available */ }
182
83
 
183
84
  // Recursively convert included relation values to class instances
184
85
  if (include) {
@@ -442,8 +343,8 @@ export class Ad4mModel {
442
343
  ...(options.getter !== undefined && { getter: options.getter }),
443
344
  ...(options.prologSetter !== undefined && { prologSetter: options.prologSetter }),
444
345
  ...(options.local !== undefined && { local: options.local }),
445
- ...(options.transform !== undefined && { transform: options.transform }),
446
- ...(options.flag !== undefined && { flag: options.flag })
346
+ ...(options.flag !== undefined && { flag: options.flag }),
347
+ ...(options.transform !== undefined && { transform: options.transform })
447
348
  };
448
349
  }
449
350
 
@@ -659,7 +560,8 @@ export class Ad4mModel {
659
560
  * • `null` / empty object — skip ALL relations (used by bare
660
561
  * subscriptions that don't eagerly load relations).
661
562
  */
662
- private takeSnapshot(includedRelations?: Record<string, any> | null): void {
563
+ /** @internal */
564
+ protected takeSnapshot(includedRelations?: Record<string, any> | null): void {
663
565
  const ctor = this.constructor as typeof Ad4mModel;
664
566
  const metadata = ctor.getModelMetadata();
665
567
  const snap: Record<string, any> = {};
@@ -866,181 +768,18 @@ export class Ad4mModel {
866
768
 
867
769
  /**
868
770
  * Build the JSON parameters needed for a model query/subscription endpoint.
869
- * Returns the className, queryJson, and shapeJson that the Rust executor expects.
771
+ * Returns the className and queryJson that the Rust executor expects.
772
+ * Shape resolution happens server-side from the perspective's SHACL triples.
870
773
  * @internal
871
774
  */
872
775
  static prepareModelQueryParams(
873
776
  query: Query = {},
874
777
  classNameOverride?: string | null,
875
- ): { className: string; queryJson: string; shapeJson: string } {
876
- const metadata = this.getModelMetadata();
877
- const className = classNameOverride || metadata.className;
878
-
879
- const queryInput: any = {};
880
- if (query.parent) {
881
- const parentPredicate = resolveParentPredicate(query.parent, this);
882
- queryInput.parent = { id: query.parent.id, predicate: parentPredicate };
883
- }
884
- if (query.properties) queryInput.properties = query.properties;
885
- if (query.include) queryInput.include = query.include;
886
- if (query.where) queryInput.where = query.where;
887
- if (query.order) {
888
- queryInput.order = Object.entries(query.order).map(([k, v]) => [k, v]);
889
- }
890
- if (query.offset !== undefined) queryInput.offset = query.offset;
891
- if (query.limit !== undefined) queryInput.limit = query.limit;
892
- if (query.count !== undefined) queryInput.count = query.count;
893
- queryInput.deepQuery = query.deepQuery ?? true;
894
-
895
- if (query.include) {
896
- const allRelMeta = getRelationsMetadata(this as any);
897
- enrichShapeForIncludes(metadata, query.include, allRelMeta);
898
- }
899
-
900
- // Pre-compute conformance getters for Rust-side evaluation.
901
- // Where clauses are NOT compiled into getter SPARQL because stored
902
- // property values are signed expression envelopes (literal:json:...),
903
- // not simple literal:string:X values. Instead, where clauses are
904
- // attached as metadata for Rust-side post-evaluation filtering.
905
- {
906
- const allRelMeta = getRelationsMetadata(this as any);
907
- for (const [relName, relMeta] of Object.entries(metadata.relations)) {
908
- const rel = relMeta as any;
909
- if (rel.getter || rel.direction === 'reverse' || rel.filter === false) continue;
910
- const meta = allRelMeta[relName];
911
- if (!meta?.target) continue;
912
- try {
913
- const TargetClass = meta.target();
914
- const filter = buildConformanceFilter(meta.predicate, TargetClass);
915
-
916
- if (filter) {
917
- rel.getter = filter.getter;
918
- }
919
-
920
- // Attach where-clause metadata for Rust-side post-getter filtering
921
- if (rel.where) {
922
- try {
923
- const targetMetadata = (TargetClass as any).getModelMetadata?.() ?? null;
924
- if (targetMetadata) {
925
- const predicates: Record<string, string> = {};
926
- for (const propName of Object.keys(rel.where)) {
927
- if (['id', 'author', 'timestamp'].includes(propName)) continue;
928
- const propMeta = targetMetadata.properties[propName];
929
- if (propMeta?.predicate) {
930
- predicates[propName] = propMeta.predicate;
931
- }
932
- }
933
- if (Object.keys(predicates).length > 0) {
934
- rel.whereFilter = rel.where;
935
- rel.wherePredicates = predicates;
936
- }
937
- }
938
- } catch (_) {}
939
- }
940
- } catch (_) {}
941
- }
942
- }
943
-
944
- return {
945
- className,
946
- queryJson: JSON.stringify(queryInput),
947
- shapeJson: JSON.stringify(metadata),
948
- };
949
- }
950
-
951
- /**
952
- * Parse raw model query/subscription result JSON into typed model instances.
953
- * Used by ModelQueryBuilder to convert subscription updates without circular imports.
954
- * @internal
955
- */
956
- static parseModelResult<T extends Ad4mModel>(
957
- this: typeof Ad4mModel & (new (...args: any[]) => T),
958
- perspective: PerspectiveProxy,
959
- raw: any,
960
- include?: IncludeMap,
961
- properties?: string[],
962
- ): T[] {
963
- const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
964
- const arr = data.instances || data;
965
- if (!Array.isArray(arr)) return [];
966
- return arr.map((json: any) => jsonToModelInstance(this, perspective, json, include, properties));
967
- }
968
-
969
- /**
970
- * Resolve non-literal (file-language) properties on an array of already-constructed
971
- * model instances. Handles two cases:
972
- *
973
- * 1. The Rust executor returned a raw URI string → fetch via `getExpression` then apply transform.
974
- * 2. The Rust executor already resolved the expression and returned a `FileData` object
975
- * (happens when the perspective backend eagerly fetches file content) → apply transform
976
- * (or `defaultFileDecode` if no transform is registered on the class, e.g. for SHACL-
977
- * synthesised model classes).
978
- *
979
- * Extracted as a public static so `ModelQueryBuilder.subscribe()` can reuse it without
980
- * duplicating logic or introducing a circular dependency.
981
- * @internal
982
- */
983
- static async resolveNonLiteralProps<T extends Ad4mModel>(
984
- this: typeof Ad4mModel & (new (...args: any[]) => T),
985
- perspective: PerspectiveProxy,
986
- instances: T[],
987
- ): Promise<void> {
988
- const propsMeta = getPropertiesMetadata(this as any);
989
- const resolveProps = Object.entries(propsMeta).filter(
990
- ([, opts]: [string, any]) =>
991
- opts.resolveLanguage != null &&
992
- opts.resolveLanguage !== 'literal',
993
- );
994
- if (resolveProps.length === 0) return;
995
-
996
- await Promise.all(
997
- instances.map(async (inst: any) => {
998
- for (const [propName, opts] of resolveProps) {
999
- const val = inst[propName];
1000
- const transform = (opts as any).transform;
1001
- const applyTransform = (resolved: unknown) =>
1002
- typeof transform === 'function' ? transform(resolved) : defaultFileDecode(resolved);
1003
-
1004
- if (typeof val === 'string' && val && !val.startsWith('literal:')) {
1005
- // Case 1: raw URI — fetch from language runtime
1006
- try {
1007
- const expression = await perspective.getExpression(val);
1008
- if (expression) {
1009
- let resolved: any;
1010
- try { resolved = JSON.parse(expression.data); } catch { resolved = expression.data; }
1011
- inst[propName] = applyTransform(resolved);
1012
- }
1013
- } catch (_) { /* resolution failed — keep raw value */ }
1014
- } else if (val !== null && val !== undefined && typeof val === 'object') {
1015
- // Case 2: already resolved by Rust — apply transform / default decode
1016
- inst[propName] = applyTransform(val);
1017
- }
1018
- }
1019
- }),
1020
- );
1021
- }
1022
-
1023
- // instancesFromQueryResult — removed (superseded by Rust executeModelQuery pipeline)
1024
-
1025
- /**
1026
- * Execute a model query via the executor-side endpoint.
1027
- *
1028
- * This replaces the old SPARQL-build → hydrate → JS-filter → JS-sort → JS-paginate pipeline
1029
- * with a single RPC to the executor that handles everything in Rust.
1030
- *
1031
- * @internal
1032
- */
1033
- private static async executeModelQuery<T extends Ad4mModel>(
1034
- this: typeof Ad4mModel & (new (...args: any[]) => T),
1035
- perspective: PerspectiveProxy,
1036
- query: Query = {},
1037
- classNameOverride?: string | null,
1038
- ): Promise<ResultsWithTotalCount<T>> {
778
+ ): { className: string; queryJson: string; metadata: ModelMetadata } {
1039
779
  const metadata = this.getModelMetadata();
1040
780
  const className = classNameOverride || metadata.className;
1041
781
 
1042
782
  // Expand includeAll: true to a full IncludeMap covering every forward relation.
1043
- // Done before queryInput is built so all downstream uses of query.include see the expansion.
1044
783
  if (query.includeAll) {
1045
784
  const allRelMeta = getRelationsMetadata(this as any);
1046
785
  const expanded: IncludeMap = {};
@@ -1049,12 +788,9 @@ export class Ad4mModel {
1049
788
  expanded[relName] = true;
1050
789
  }
1051
790
  }
1052
- // Explicit include entries take precedence over the expansion
1053
791
  query = { ...query, include: { ...expanded, ...query.include } };
1054
792
  }
1055
793
 
1056
- // Build the query input that the Rust endpoint expects.
1057
- // Convert the TS Query type to the executor's ModelQueryInput format.
1058
794
  const queryInput: any = {};
1059
795
  if (query.parent) {
1060
796
  const parentPredicate = resolveParentPredicate(query.parent, this);
@@ -1075,18 +811,20 @@ export class Ad4mModel {
1075
811
  }
1076
812
  if (Object.keys(normalIncludes).length > 0) queryInput.include = normalIncludes;
1077
813
  if (Object.keys(projections).length > 0) {
1078
- // Enrich projections with target shapes so Rust can apply where clause filtering
814
+ // Tag each projection with its target class name so the executor can
815
+ // resolve the target shape through its in-memory cache when applying
816
+ // projection where-clause filters.
1079
817
  const allRelMeta = getRelationsMetadata(this as any);
1080
818
  for (const [, proj] of Object.entries(projections)) {
1081
819
  const relMeta = allRelMeta[proj.from];
1082
- if (!proj.targetShape && relMeta?.target) {
820
+ if (!proj.targetClassName && relMeta?.target) {
1083
821
  try {
1084
822
  const TargetClass = relMeta.target();
1085
823
  const targetMeta = (TargetClass as any).getModelMetadata?.();
1086
- if (targetMeta) {
1087
- proj.targetShape = targetMeta;
824
+ if (targetMeta?.className) {
825
+ proj.targetClassName = targetMeta.className;
1088
826
  }
1089
- } catch (_) { /* target class may not be available */ }
827
+ } catch (e) { console.debug(`prepareModelQueryParams: target class unavailable for projection:`, e); }
1090
828
  }
1091
829
  }
1092
830
  queryInput.projections = projections;
@@ -1094,7 +832,6 @@ export class Ad4mModel {
1094
832
  }
1095
833
  if (query.where) queryInput.where = query.where;
1096
834
  if (query.order) {
1097
- // Convert { propName: 'ASC' | 'DESC' } to [[propName, 'ASC'|'DESC'], ...]
1098
835
  queryInput.order = Object.entries(query.order).map(([k, v]) => [k, v]);
1099
836
  }
1100
837
  if (query.offset !== undefined) queryInput.offset = query.offset;
@@ -1102,74 +839,59 @@ export class Ad4mModel {
1102
839
  if (query.count !== undefined) queryInput.count = query.count;
1103
840
  queryInput.deepQuery = query.deepQuery ?? true;
1104
841
 
1105
- // Enrich relation metadata with target class shapes for Rust-side
1106
- // include resolution. This eliminates per-relation GraphQL round-trips
1107
- // by letting the Rust endpoint resolve includes in-process.
1108
- if (queryInput.include) {
1109
- const allRelMeta = getRelationsMetadata(this as any);
1110
- enrichShapeForIncludes(metadata, queryInput.include, allRelMeta);
1111
- }
1112
-
1113
- // ── Pre-compute conformance getters for Rust-side evaluation ──────
1114
- // For each relation with a target class and filter !== false, compute
1115
- // the conformance getter SPARQL so Rust can evaluate it in-process
1116
- // (eliminating N × querySparql round-trips per instance).
1117
- // When a relation has a `where` clause, compile the where conditions
1118
- // into the getter SPARQL so Rust applies them during evaluation.
1119
- {
1120
- const allRelMeta = getRelationsMetadata(this as any);
1121
- for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1122
- const rel = relMeta as any;
1123
- if (rel.getter) continue; // explicit getter already set
1124
- if (rel.direction === 'reverse') continue; // reverse relations use reverse link lookup
1125
- if (rel.filter === false) continue; // opt-out of conformance filtering
842
+ // Conformance getters, where filters, and target shapes for includes
843
+ // are all resolved by the executor from the perspective's SHACL triples
844
+ // — no client-side pre-computation is needed any more.
1126
845
 
1127
- const meta = allRelMeta[relName];
1128
- if (!meta?.target) continue;
846
+ return {
847
+ className,
848
+ queryJson: JSON.stringify(queryInput),
849
+ metadata,
850
+ };
851
+ }
1129
852
 
1130
- try {
1131
- const TargetClass = meta.target();
1132
- const filter = buildConformanceFilter(meta.predicate, TargetClass);
853
+ /**
854
+ * Parse raw model query/subscription result JSON into typed model instances.
855
+ * Used by ModelQueryBuilder to convert subscription updates without circular imports.
856
+ * @internal
857
+ */
858
+ static parseModelResult<T extends Ad4mModel>(
859
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
860
+ perspective: PerspectiveProxy,
861
+ raw: any,
862
+ include?: IncludeMap,
863
+ properties?: string[],
864
+ ): T[] {
865
+ const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
866
+ const arr = data.instances || data;
867
+ if (!Array.isArray(arr)) return [];
868
+ return arr.map((json: any) => jsonToModelInstance(this, perspective, json, include, properties));
869
+ }
1133
870
 
1134
- if (filter) {
1135
- rel.getter = filter.getter;
1136
- }
1137
871
 
1138
- // Attach where-clause metadata for Rust-side post-getter filtering.
1139
- // Property values are signed expression envelopes (literal:json:...)
1140
- // and cannot be matched by SPARQL FILTER on the raw IRI.
1141
- if (rel.where) {
1142
- try {
1143
- const targetMetadata = (TargetClass as any).getModelMetadata?.() ?? null;
1144
- if (targetMetadata) {
1145
- const predicates: Record<string, string> = {};
1146
- for (const propName of Object.keys(rel.where)) {
1147
- if (['id', 'author', 'timestamp'].includes(propName)) continue;
1148
- const propMeta = targetMetadata.properties[propName];
1149
- if (propMeta?.predicate) {
1150
- predicates[propName] = propMeta.predicate;
1151
- }
1152
- }
1153
- if (Object.keys(predicates).length > 0) {
1154
- rel.whereFilter = rel.where;
1155
- rel.wherePredicates = predicates;
1156
- }
1157
- }
1158
- } catch (_) { /* target metadata unavailable */ }
1159
- }
1160
- } catch (e) {
1161
- // Target class may not be available; skip silently
1162
- }
1163
- }
1164
- }
872
+ // instancesFromQueryResult — removed (superseded by Rust executeModelQuery pipeline)
1165
873
 
1166
- // Send shape metadata to the executor so it knows the model structure.
1167
- // This is more reliable than reading SHACL from the store because
1168
- // the TS decorators are the definitive source of truth.
1169
- const shapeJson = JSON.stringify(metadata);
1170
- const queryJson = JSON.stringify(queryInput);
874
+ /**
875
+ * Execute a model query via the executor-side endpoint.
876
+ *
877
+ * This replaces the old SPARQL-build → hydrate → JS-filter → JS-sort → JS-paginate pipeline
878
+ * with a single RPC to the executor that handles everything in Rust.
879
+ *
880
+ * @internal
881
+ */
882
+ private static async executeModelQuery<T extends Ad4mModel>(
883
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
884
+ perspective: PerspectiveProxy,
885
+ query: Query = {},
886
+ classNameOverride?: string | null,
887
+ ): Promise<ResultsWithTotalCount<T>> {
888
+ // Delegate query input building to the shared prepareModelQueryParams
889
+ // helper. The executor resolves the shape from SHACL server-side.
890
+ const { className, queryJson } = this.prepareModelQueryParams(
891
+ query, classNameOverride,
892
+ );
1171
893
 
1172
- const result = await perspective.modelQuery(className, queryJson, shapeJson);
894
+ const result = await perspective.modelQuery(className, queryJson);
1173
895
 
1174
896
  // Convert JSON instances to model class instances, recursively constructing
1175
897
  // class instances for any included relations resolved by Rust.
@@ -1177,16 +899,14 @@ export class Ad4mModel {
1177
899
  return jsonToModelInstance(this, perspective, json, query.include, query.properties);
1178
900
  });
1179
901
 
1180
- // Resolve non-literal expressions (e.g. file languages where the stored
1181
- // value is a content-addressed hash that must be fetched from the language
1182
- // runtime). The Rust endpoint may return either a raw target URI (string)
1183
- // or an already-resolved FileData object — both cases are handled here.
1184
- await (this as any).resolveNonLiteralProps(perspective, instances);
1185
-
1186
- // Take snapshots for dirty tracking
1187
- const snapshotRelations = queryInput.include;
902
+ // Take snapshots for dirty tracking (exclude $-prefixed projection keys)
903
+ const snapshotRelations = query.include
904
+ ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
905
+ : undefined;
1188
906
  for (const inst of instances) {
1189
- (inst as Ad4mModel).takeSnapshot(snapshotRelations);
907
+ (inst as Ad4mModel).takeSnapshot(
908
+ snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined,
909
+ );
1190
910
  }
1191
911
 
1192
912
  return {
@@ -1200,40 +920,36 @@ export class Ad4mModel {
1200
920
  *
1201
921
  * @param perspective - The perspective to search in
1202
922
  * @param query - Optional query parameters to filter results
1203
- * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
923
+ * @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
924
+ * All queries now use the Rust SPARQL pipeline.
1204
925
  * @returns Array of matching models
1205
- *
926
+ *
1206
927
  * @example
1207
928
  * ```typescript
1208
- * // Get all recipes (uses SPARQL by default)
1209
929
  * const allRecipes = await Recipe.findAll(perspective);
1210
- *
1211
- * // Get recipes with specific criteria (uses SPARQL)
930
+ *
1212
931
  * const recipes = await Recipe.findAll(perspective, {
1213
- * where: {
932
+ * where: {
1214
933
  * name: "Pasta",
1215
934
  * rating: { gt: 4 }
1216
935
  * },
1217
936
  * order: { createdAt: "DESC" },
1218
937
  * limit: 10
1219
938
  * });
1220
- *
1221
- * // Explicitly use Prolog (legacy, for backward compatibility)
1222
- * const recipesProlog = await Recipe.findAll(perspective, {}, false);
1223
939
  * ```
1224
940
  */
1225
- static async findAll<T extends Ad4mModel>(
1226
- this: typeof Ad4mModel & (new (...args: any[]) => T),
1227
- perspective: PerspectiveProxy,
1228
- query: Query = {},
1229
- _engine?: 'sparql' | 'prolog' | boolean
1230
- ): Promise<T[]> {
1231
- if (query.properties && query.properties.length === 0) {
941
+ static async findAll<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(
942
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
943
+ perspective: PerspectiveProxy,
944
+ query?: Q,
945
+ ): Promise<(T & IncludeExtras<T, IncludeOf<Q>>)[]> {
946
+ const q = (query ?? {}) as Query;
947
+ if (q.properties && q.properties.length === 0) {
1232
948
  throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
1233
949
  }
1234
950
 
1235
- const { results } = await this.executeModelQuery(perspective, query);
1236
- return results;
951
+ const { results } = await this.executeModelQuery(perspective, q);
952
+ return results as (T & IncludeExtras<T, IncludeOf<Q>>)[];
1237
953
  }
1238
954
 
1239
955
  /**
@@ -1243,7 +959,7 @@ export class Ad4mModel {
1243
959
  *
1244
960
  * @param perspective - The perspective to search in
1245
961
  * @param query - Optional query parameters to filter results
1246
- * @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
962
+ * @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
1247
963
  * @returns The first matching instance, or `null`
1248
964
  *
1249
965
  * @example
@@ -1256,14 +972,13 @@ export class Ad4mModel {
1256
972
  * }
1257
973
  * ```
1258
974
  */
1259
- static async findOne<T extends Ad4mModel>(
975
+ static async findOne<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(
1260
976
  this: typeof Ad4mModel & (new (...args: any[]) => T),
1261
977
  perspective: PerspectiveProxy,
1262
- query: Query = {},
1263
- _engine?: 'sparql' | 'prolog' | boolean,
1264
- ): Promise<T | null> {
1265
- const limitedQuery = { ...query, limit: 1 };
1266
- const results = await this.findAll(perspective, limitedQuery);
978
+ query?: Q,
979
+ ): Promise<(T & IncludeExtras<T, IncludeOf<Q>>) | null> {
980
+ const limitedQuery = { ...((query ?? {}) as Query), limit: 1 } as Q;
981
+ const results = await this.findAll<T, Q>(perspective, limitedQuery);
1267
982
  return results[0] ?? null;
1268
983
  }
1269
984
 
@@ -1272,9 +987,9 @@ export class Ad4mModel {
1272
987
  *
1273
988
  * @param perspective - The perspective to search in
1274
989
  * @param query - Optional query parameters to filter results
1275
- * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
990
+ * @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
1276
991
  * @returns Object containing results array and total count
1277
- *
992
+ *
1278
993
  * @example
1279
994
  * ```typescript
1280
995
  * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {
@@ -1282,18 +997,15 @@ export class Ad4mModel {
1282
997
  * limit: 10
1283
998
  * });
1284
999
  * console.log(`Showing 10 of ${totalCount} dessert recipes`);
1285
- *
1286
- * // Use Prolog explicitly (legacy)
1287
- * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
1288
1000
  * ```
1289
1001
  */
1290
- static async findAllAndCount<T extends Ad4mModel>(
1291
- this: typeof Ad4mModel & (new (...args: any[]) => T),
1292
- perspective: PerspectiveProxy,
1293
- query: Query = {},
1294
- _engine?: 'sparql' | 'prolog' | boolean
1295
- ): Promise<ResultsWithTotalCount<T>> {
1296
- return await this.executeModelQuery(perspective, query);
1002
+ static async findAllAndCount<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(
1003
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
1004
+ perspective: PerspectiveProxy,
1005
+ query?: Q,
1006
+ ): Promise<ResultsWithTotalCount<T & IncludeExtras<T, IncludeOf<Q>>>> {
1007
+ const out = await this.executeModelQuery(perspective, (query ?? {}) as Query);
1008
+ return out as ResultsWithTotalCount<T & IncludeExtras<T, IncludeOf<Q>>>;
1297
1009
  }
1298
1010
 
1299
1011
  /**
@@ -1313,17 +1025,16 @@ export class Ad4mModel {
1313
1025
  * console.log(`Page ${page.pageNumber} of recipes, ${page.results.length} items`);
1314
1026
  * ```
1315
1027
  */
1316
- static async paginate<T extends Ad4mModel>(
1317
- this: typeof Ad4mModel & (new (...args: any[]) => T),
1318
- perspective: PerspectiveProxy,
1319
- pageSize: number,
1320
- pageNumber: number,
1321
- query?: Query,
1322
- _engine?: 'sparql' | 'prolog' | boolean
1323
- ): Promise<PaginationResult<T>> {
1324
- const paginationQuery = { ...(query || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
1028
+ static async paginate<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(
1029
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
1030
+ perspective: PerspectiveProxy,
1031
+ pageSize: number,
1032
+ pageNumber: number,
1033
+ query?: Q,
1034
+ ): Promise<PaginationResult<T & IncludeExtras<T, IncludeOf<Q>>>> {
1035
+ const paginationQuery = { ...((query ?? {}) as Query), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
1325
1036
  const { results, totalCount } = await this.executeModelQuery(perspective, paginationQuery);
1326
- return { results, totalCount, pageSize, pageNumber };
1037
+ return { results: results as (T & IncludeExtras<T, IncludeOf<Q>>)[], totalCount, pageSize, pageNumber };
1327
1038
  }
1328
1039
 
1329
1040
  /**
@@ -1352,8 +1063,12 @@ export class Ad4mModel {
1352
1063
  * });
1353
1064
  * ```
1354
1065
  */
1355
- static async count(perspective: PerspectiveProxy, query: Query = {}): Promise<number> {
1356
- const { totalCount } = await this.executeModelQuery(perspective, { ...query, limit: 0 });
1066
+ static async count<T extends Ad4mModel>(
1067
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
1068
+ perspective: PerspectiveProxy,
1069
+ query?: TypedQuery<T>,
1070
+ ): Promise<number> {
1071
+ const { totalCount } = await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), limit: 0 });
1357
1072
  return totalCount;
1358
1073
  }
1359
1074
 
@@ -1717,28 +1432,13 @@ export class Ad4mModel {
1717
1432
  if (instances.length === 0) return;
1718
1433
  const metadata = this.getModelMetadata();
1719
1434
 
1720
- // Pre-compute conformance getters so the shape sent to Rust includes them
1721
- const allRelMeta = getRelationsMetadata(this as any);
1722
- for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1723
- const rel = relMeta as any;
1724
- if (rel.getter || rel.direction === 'reverse' || rel.filter === false) continue;
1725
- const meta = allRelMeta[relName];
1726
- if (!meta?.target) continue;
1727
- try {
1728
- const TargetClass = meta.target();
1729
- const filter = buildConformanceFilter(meta.predicate, TargetClass);
1730
- if (filter) rel.getter = filter.getter;
1731
- } catch (_) { /* target class may not be available */ }
1732
- }
1733
-
1734
- const shapeJson = JSON.stringify(metadata);
1735
1435
  const instanceIds = instances.map(inst => inst.id || (inst as any)._baseExpression);
1736
1436
 
1737
- // Single RPC call evaluates all getters in-process on the executor
1437
+ // The executor reads getter SPARQL from the perspective's SHACL triples
1438
+ // (written by `addSdna`), so no shape JSON is shipped with the call.
1738
1439
  const result = await perspective.evaluateGetters(
1739
1440
  metadata.className,
1740
1441
  instanceIds,
1741
- shapeJson,
1742
1442
  propertyNames,
1743
1443
  );
1744
1444
 
@@ -2068,6 +1768,26 @@ export class Ad4mModel {
2068
1768
  await perspective.ensureSDNASubjectClass(this);
2069
1769
  }
2070
1770
 
1771
+ /**
1772
+ * Batch-registers multiple model classes on a perspective in a single RPC call.
1773
+ * This is significantly faster than calling `register()` on each model individually
1774
+ * because it eliminates N-1 round-trips and mutex acquisitions.
1775
+ *
1776
+ * @param perspective - The perspective to register the models on
1777
+ * @param models - Array of Ad4mModel subclasses to register
1778
+ *
1779
+ * @example
1780
+ * ```typescript
1781
+ * await Ad4mModel.registerAll(perspective, [Community, Channel, Message, Task]);
1782
+ * ```
1783
+ */
1784
+ static async registerAll(
1785
+ perspective: PerspectiveProxy,
1786
+ models: (typeof Ad4mModel)[],
1787
+ ): Promise<void> {
1788
+ await perspective.ensureSubjectClasses(models);
1789
+ }
1790
+
2071
1791
  /**
2072
1792
  * Executes a set of model operations inside a single batch (transaction).
2073
1793
  *
@@ -2129,11 +1849,11 @@ export class Ad4mModel {
2129
1849
  * ```
2130
1850
  */
2131
1851
  static query<T extends Ad4mModel>(
2132
- this: typeof Ad4mModel & (new (...args: any[]) => T),
2133
- perspective: PerspectiveProxy,
2134
- query?: Query
1852
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
1853
+ perspective: PerspectiveProxy,
1854
+ query?: TypedQuery<T>,
2135
1855
  ): ModelQueryBuilder<T> {
2136
- return new ModelQueryBuilder<T>(perspective, this as any, query);
1856
+ return new ModelQueryBuilder<T>(perspective, this as any, (query ?? {}) as Query);
2137
1857
  }
2138
1858
 
2139
1859
  /**