@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
@@ -27,6 +27,68 @@ import type { Where, Query, ModelMetadata } from "./types";
27
27
  * potentially discarding matches beyond the LIMIT.
28
28
  */
29
29
  export declare function hasJsOnlyWhereFilters(metadata: ModelMetadata, allRelationsMetadata: Record<string, RelationMetadataEntry>, where?: Where): boolean;
30
+ /**
31
+ * Check whether a string value is a well-formed absolute IRI that can be
32
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
33
+ * wrapped in a `literal:string:*` URI.
34
+ *
35
+ * This mirrors the Rust `is_safe_iri_target` /
36
+ * `looks_like_absolute_iri` predicate in
37
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
38
+ * **load-bearing**: a value that returns `true` here MUST also be safely
39
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
40
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
41
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
42
+ * through the write regex, is stored as an invalid `NamedNode`, and
43
+ * becomes a silent no-match on read.
44
+ *
45
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
46
+ * same rejection set the Rust `validate_iri` applies: any Unicode
47
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
48
+ * `< > { } "`.
49
+ */
50
+ export declare function looksLikeUri(value: string): boolean;
51
+ /**
52
+ * Convert a JS value to its literal: IRI form, matching how the Rust executor
53
+ * stores property values in the default deterministic-literal path
54
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
55
+ * as-is.
56
+ *
57
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
58
+ * resolve path) can keep their on-disk form aligned with what
59
+ * `queryToSPARQL()` filters against — otherwise the same value can be
60
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
61
+ * builders probe `<https://example.com>` from the other.
62
+ *
63
+ * The object/array arm mirrors Rust's `Literal::from_json` in
64
+ * `perspective_instance.rs::resolve_property_value` (which routes
65
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
66
+ * would fall through to `String(value)` and turn `{a: 1}` into
67
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
68
+ */
69
+ export declare function valueToLiteralIri(value: any): string;
70
+ /** How a property's value is stored / resolved. */
71
+ export type LiteralStorageMode = {
72
+ kind: "deterministic";
73
+ } | {
74
+ kind: "envelope";
75
+ } | {
76
+ kind: "custom";
77
+ language: string;
78
+ };
79
+ /**
80
+ * Derive the effective storage mode from a property's explicit options.
81
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
82
+ * decorator level:
83
+ * - unset → deterministic typed literal (the perf default
84
+ * for a plain `@Property()`)
85
+ * - `"literal"` → signed envelope on the built-in literal language
86
+ * (per-value provenance, e.g. Flux message bodies)
87
+ * - `<custom address>` → signed expression on that custom language
88
+ */
89
+ export declare function effectiveLiteralStorage(meta: {
90
+ resolveLanguage?: string;
91
+ }): LiteralStorageMode;
30
92
  /**
31
93
  * Format a value as a SPARQL string literal (double-quoted).
32
94
  */
@@ -70,17 +70,54 @@ export function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
70
70
  return false;
71
71
  }
72
72
  /**
73
- * Check if a string value looks like a URI (has a scheme).
73
+ * Check whether a string value is a well-formed absolute IRI that can be
74
+ * stored verbatim as a link target (raw `NamedNode`) instead of being
75
+ * wrapped in a `literal:string:*` URI.
76
+ *
77
+ * This mirrors the Rust `is_safe_iri_target` /
78
+ * `looks_like_absolute_iri` predicate in
79
+ * `rust-executor/src/perspectives/model_query/utils.rs` and is
80
+ * **load-bearing**: a value that returns `true` here MUST also be safely
81
+ * queryable on the Rust side (`validate_iri` gate on the SPARQL
82
+ * `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
83
+ * such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
84
+ * through the write regex, is stored as an invalid `NamedNode`, and
85
+ * becomes a silent no-match on read.
86
+ *
87
+ * Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
88
+ * same rejection set the Rust `validate_iri` applies: any Unicode
89
+ * whitespace, C0/C1 control chars, and the SPARQL-breaking characters
90
+ * `< > { } "`.
74
91
  */
75
- function looksLikeUri(value) {
76
- return /^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value);
92
+ export function looksLikeUri(value) {
93
+ if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value))
94
+ return false;
95
+ // Reject anything the Rust-side `validate_iri` rejects so the two
96
+ // predicates stay in sync. `\s` covers ASCII whitespace *and*
97
+ // U+00A0/other Unicode whitespace under the default JS regex semantics.
98
+ if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value))
99
+ return false;
100
+ return true;
77
101
  }
78
102
  /**
79
103
  * Convert a JS value to its literal: IRI form, matching how the Rust executor
80
- * stores property values that don't have a resolveLanguage set.
81
- * Strings that already look like URIs are returned as-is.
104
+ * stores property values in the default deterministic-literal path
105
+ * (`resolveLanguage` unset). Strings that already look like URIs are returned
106
+ * as-is.
107
+ *
108
+ * Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
109
+ * resolve path) can keep their on-disk form aligned with what
110
+ * `queryToSPARQL()` filters against — otherwise the same value can be
111
+ * stored as `<literal:string:https%3A...>` from one path while WHERE
112
+ * builders probe `<https://example.com>` from the other.
113
+ *
114
+ * The object/array arm mirrors Rust's `Literal::from_json` in
115
+ * `perspective_instance.rs::resolve_property_value` (which routes
116
+ * `Value::Object | Value::Array` through JSON encoding). Without it, JS
117
+ * would fall through to `String(value)` and turn `{a: 1}` into
118
+ * `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
82
119
  */
83
- function valueToLiteralIri(value) {
120
+ export function valueToLiteralIri(value) {
84
121
  if (typeof value === 'string') {
85
122
  if (looksLikeUri(value))
86
123
  return value;
@@ -92,22 +129,48 @@ function valueToLiteralIri(value) {
92
129
  if (typeof value === 'boolean') {
93
130
  return Literal.from(value).toUrl();
94
131
  }
132
+ // Objects and arrays: route through Literal.from so we emit
133
+ // `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
134
+ // arm we fall through to `String(value)` which turns objects into
135
+ // `"[object Object]"` and arrays into `"1,2"` — silently storing the
136
+ // wrong shape and breaking equality filters (`findAll({ where:
137
+ // { config: {...} } })` would match against `"[object Object]"`).
138
+ // The `value !== null` guard preserves the historical fallthrough for
139
+ // `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
140
+ // throws on the empty-literal check.
141
+ if (value !== null && typeof value === 'object') {
142
+ return Literal.from(value).toUrl();
143
+ }
95
144
  return Literal.from(String(value)).toUrl();
96
145
  }
97
146
  /**
98
- * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
99
- * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
100
- * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
101
- * (e.g. file storage) or flag properties store raw URIs.
147
+ * Derive the effective storage mode from a property's explicit options.
148
+ * `resolveLanguage` is the sole selector and is NOT defaulted at the
149
+ * decorator level:
150
+ * - unset → deterministic typed literal (the perf default
151
+ * for a plain `@Property()`)
152
+ * - `"literal"` → signed envelope on the built-in literal language
153
+ * (per-value provenance, e.g. Flux message bodies)
154
+ * - `<custom address>` → signed expression on that custom language
155
+ */
156
+ export function effectiveLiteralStorage(meta) {
157
+ const lang = meta.resolveLanguage;
158
+ if (lang === undefined)
159
+ return { kind: "deterministic" };
160
+ if (lang === "literal")
161
+ return { kind: "envelope" };
162
+ return { kind: "custom", language: lang };
163
+ }
164
+ /**
165
+ * Determine if a property stores values as deterministic literal: IRIs (so WHERE
166
+ * filters can match typed literals directly). Envelope / custom-language
167
+ * properties resolve through expressions, and flag properties store raw URIs —
168
+ * none is a deterministic literal.
102
169
  */
103
170
  function isLiteralStoredProperty(propMeta) {
104
171
  if (propMeta.flag)
105
172
  return false;
106
- // If resolveLanguage is set to something other than "literal", it's a language expression URI
107
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal")
108
- return false;
109
- // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
110
- return true;
173
+ return effectiveLiteralStorage(propMeta).kind === "deterministic";
111
174
  }
112
175
  /**
113
176
  * Escape a string for use as a SPARQL string literal.
@@ -53,26 +53,28 @@ describe('hasJsOnlyWhereFilters', () => {
53
53
  expect(hasJsOnlyWhereFilters(meta, relMeta, { parent: 'some://id' })).toBe(true);
54
54
  });
55
55
  });
56
- describe('buildSPARQLQuery — pagination handled in JS, not SPARQL', () => {
56
+ describe('buildSPARQLQuery — SPARQL-level pagination via subquery', () => {
57
57
  const modelClass = {};
58
- it('does NOT include LIMIT/OFFSET in SPARQL even when query has them', () => {
58
+ it('includes LIMIT/OFFSET in a pagination subquery when query has them and no JS-only filters', () => {
59
59
  const query = { limit: 10, offset: 0, where: { category: 'some://uri' } };
60
60
  const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
61
- // SPARQL should NOT contain LIMIT/OFFSET — pagination is done in JS
62
- expect(sparql).not.toContain('LIMIT');
63
- expect(sparql).not.toContain('OFFSET');
61
+ // SPARQL should contain LIMIT inside the pagination subquery
62
+ expect(sparql).toContain('LIMIT 10');
64
63
  // The outer query should still exist
65
64
  expect(sparql).toContain('SELECT ?source ?predicate ?target');
65
+ // Should have a subquery pattern
66
+ expect(sparql).toContain('SELECT DISTINCT ?source');
66
67
  });
67
- it('does NOT include LIMIT/OFFSET even with JS-only where filters', () => {
68
- const query = { limit: 10, offset: 0, where: { name: 'Pasta' } };
68
+ it('does NOT include LIMIT/OFFSET when JS-only where filters exist', () => {
69
+ // author is a JS-only filter
70
+ const query = { limit: 10, offset: 0, where: { author: 'did:key:abc' } };
69
71
  const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
70
72
  expect(sparql).not.toContain('LIMIT');
71
73
  expect(sparql).not.toContain('OFFSET');
72
74
  });
73
75
  });
74
76
  describe('buildSPARQLOrderLimitOffset', () => {
75
- it('always returns empty string (pagination is handled in JS)', () => {
77
+ it('always returns empty string (pagination uses subquery pattern instead)', () => {
76
78
  expect(buildSPARQLOrderLimitOffset(emptyMetadata, {})).toBe('');
77
79
  expect(buildSPARQLOrderLimitOffset(emptyMetadata, { limit: 50 })).toBe('');
78
80
  expect(buildSPARQLOrderLimitOffset(emptyMetadata, { limit: 50, offset: 100 })).toBe('');
@@ -132,8 +134,9 @@ describe('buildSPARQLQuery — structural correctness', () => {
132
134
  };
133
135
  const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
134
136
  expect(sparql).toContain('<flux://channel-123>');
135
- // No SPARQL-level pagination
136
- expect(sparql).not.toContain('LIMIT');
137
+ // SPARQL-level pagination via subquery
138
+ expect(sparql).toContain('LIMIT 50');
139
+ expect(sparql).toContain('SELECT DISTINCT ?source');
137
140
  });
138
141
  it('does not allow injection through where clause IRI values', () => {
139
142
  const query = {
@@ -208,6 +211,67 @@ describe('buildSPARQLQuery — IRI correctness', () => {
208
211
  expect(sparql).not.toContain('fn::parse_literal');
209
212
  });
210
213
  });
214
+ // ──────────────────────────────────────────────────────────
215
+ // SPARQL-level pagination (LIMIT/OFFSET in generated queries)
216
+ // ──────────────────────────────────────────────────────────
217
+ describe('SPARQL-level pagination', () => {
218
+ const modelClass = {};
219
+ it('includes LIMIT in SPARQL when query specifies limit', () => {
220
+ const query = { limit: 30 };
221
+ const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
222
+ expect(sparql).toContain('LIMIT 30');
223
+ expect(sparql).toContain('SELECT DISTINCT ?source');
224
+ });
225
+ it('includes OFFSET in SPARQL when query specifies offset > 0', () => {
226
+ const query = { limit: 20, offset: 40 };
227
+ const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
228
+ expect(sparql).toContain('LIMIT 20');
229
+ expect(sparql).toContain('OFFSET 40');
230
+ });
231
+ it('does NOT include OFFSET when offset is 0', () => {
232
+ const query = { limit: 10, offset: 0 };
233
+ const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
234
+ expect(sparql).toContain('LIMIT 10');
235
+ expect(sparql).not.toContain('OFFSET');
236
+ });
237
+ it('includes ORDER BY in subquery when query.order is specified', () => {
238
+ const query = { limit: 10, order: { name: 'DESC' } };
239
+ const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
240
+ expect(sparql).toContain('ORDER BY DESC(');
241
+ expect(sparql).toContain('LIMIT 10');
242
+ });
243
+ it('does NOT default to ORDER BY timestamp when paginating without explicit order', () => {
244
+ const query = { limit: 30 };
245
+ const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
246
+ expect(sparql).not.toContain('ORDER BY');
247
+ expect(sparql).not.toContain('pg_minTs');
248
+ });
249
+ it('does NOT push pagination to SPARQL when JS-only where filters exist (author)', () => {
250
+ const query = { limit: 10, where: { author: 'did:key:abc' } };
251
+ const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
252
+ expect(sparql).not.toContain('LIMIT');
253
+ expect(sparql).not.toContain('OFFSET');
254
+ });
255
+ it('does NOT push pagination to SPARQL when JS-only where filters exist (gt operator)', () => {
256
+ const meta = {
257
+ properties: {
258
+ rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
259
+ },
260
+ relations: {},
261
+ };
262
+ const query = { limit: 10, where: { rating: { gt: 5 } } };
263
+ const sparql = buildSPARQLQuery(meta, emptyRelations, query, modelClass);
264
+ expect(sparql).not.toContain('LIMIT');
265
+ });
266
+ it('wraps pagination in a subquery (outer SELECT fetches all links for the page)', () => {
267
+ const query = { limit: 5, offset: 10 };
268
+ const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
269
+ expect(sparql).toContain('SELECT ?source ?predicate ?target ?author ?timestamp');
270
+ expect(sparql).toContain('SELECT DISTINCT ?source');
271
+ expect(sparql).toContain('LIMIT 5');
272
+ expect(sparql).toContain('OFFSET 10');
273
+ });
274
+ });
211
275
  describe('buildSPARQLQuery — set-difference patterns', () => {
212
276
  const modelClass = {};
213
277
  // Subgroups are grandchildren of channels (channel → conversation → subgroup).
@@ -228,3 +292,21 @@ describe('buildSPARQLQuery — set-difference patterns', () => {
228
292
  expect(sparql).toContain('SELECT ?source ?predicate ?target');
229
293
  });
230
294
  });
295
+ describe('buildSPARQLQuery — RDF 1.2 reifier patterns', () => {
296
+ const modelClass = {};
297
+ it('uses rdf:reifies instead of GRAPH for link metadata', () => {
298
+ const query = { limit: 10 };
299
+ const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
300
+ expect(sparql).toContain('<http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies>');
301
+ expect(sparql).toContain('<http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies> <<(');
302
+ expect(sparql).toContain('?_reifier');
303
+ expect(sparql).not.toContain('GRAPH');
304
+ expect(sparql).not.toContain('?linkGraph');
305
+ });
306
+ it('binds author and timestamp on the reifier node', () => {
307
+ const query = {};
308
+ const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
309
+ expect(sparql).toContain('?_reifier <ad4m://ontology/author> ?author');
310
+ expect(sparql).toContain('?_reifier <ad4m://ontology/timestamp> ?timestamp');
311
+ });
312
+ });
@@ -25,11 +25,16 @@ export declare function formatQueryValue(value: any): string;
25
25
  *
26
26
  * @param predicate - The predicate URI for the property
27
27
  * @param condition - The Where condition value
28
- * @param opts - Optional settings (e.g. `resolveLanguage`)
28
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
29
+ * `true`) selects the direct typed-literal WHERE path.
30
+ * Set to `false` when the property stores a signed
31
+ * envelope (`resolveLanguage: "literal"`) or a
32
+ * custom-language expression — the envelope path unwraps
33
+ * with `parse_literal` before comparing.
29
34
  * @returns A single SPARQL condition string
30
35
  */
31
36
  export declare function buildWhereCondition(predicate: string, condition: WhereCondition, opts?: {
32
- resolveLanguage?: string;
37
+ isDeterministicLiteral?: boolean;
33
38
  varIndex?: number;
34
39
  }): string;
35
40
  /**
@@ -46,16 +46,21 @@ export function formatQueryValue(value) {
46
46
  *
47
47
  * @param predicate - The predicate URI for the property
48
48
  * @param condition - The Where condition value
49
- * @param opts - Optional settings (e.g. `resolveLanguage`)
49
+ * @param opts - Optional settings. `isDeterministicLiteral` (default
50
+ * `true`) selects the direct typed-literal WHERE path.
51
+ * Set to `false` when the property stores a signed
52
+ * envelope (`resolveLanguage: "literal"`) or a
53
+ * custom-language expression — the envelope path unwraps
54
+ * with `parse_literal` before comparing.
50
55
  * @returns A single SPARQL condition string
51
56
  */
52
57
  export function buildWhereCondition(predicate, condition, opts) {
53
58
  const escapedPredicate = escapeQueryString(predicate);
54
- // For literal-resolved properties, we match against the raw IRI (which is a literal: URI)
55
- // For language-resolved properties, we match against the plain URI
56
- // For literal-resolved properties, values are stored as IRIs like <literal:string:VALUE>
57
- // For language-resolved properties, values are plain URIs
58
- const isLiteral = !opts?.resolveLanguage || opts.resolveLanguage === 'literal';
59
+ // For deterministic-literal properties, values are stored as typed
60
+ // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
61
+ // IRI form). For envelope / custom-language properties the target is a
62
+ // signed expression URI; comparisons need to unwrap via `parse_literal`.
63
+ const isLiteral = opts?.isDeterministicLiteral !== false;
59
64
  const varSuffix = opts?.varIndex ?? 0;
60
65
  function formatValue(v) {
61
66
  if (typeof v === 'string') {
@@ -164,23 +169,28 @@ export function compileWhereClause(where, metadata) {
164
169
  if (['id', 'author', 'timestamp'].includes(propertyName))
165
170
  continue;
166
171
  let predicate;
167
- let resolveLanguage;
172
+ // Storage mode is derived from `resolveLanguage` alone:
173
+ // - undefined → deterministic typed literal (fast POS-index path)
174
+ // - "literal" → signed envelope on the literal language
175
+ // - custom address → expression on that custom language
176
+ // Envelope and custom-language properties both need the `parse_literal`
177
+ // unwrap path, so we treat any `resolveLanguage`-carrying property as
178
+ // non-deterministic here.
179
+ let isDeterministicLiteral;
168
180
  if (metadata) {
169
181
  const propMeta = metadata.properties[propertyName];
170
182
  if (propMeta) {
171
183
  predicate = propMeta.predicate;
172
- resolveLanguage = propMeta.resolveLanguage;
184
+ isDeterministicLiteral = propMeta.resolveLanguage === undefined;
173
185
  }
174
186
  else {
175
- // Property not found in metadata — treat name as raw predicate URI
176
187
  predicate = propertyName;
177
188
  }
178
189
  }
179
190
  else {
180
- // No metadata — treat name as raw predicate URI
181
191
  predicate = propertyName;
182
192
  }
183
- const cond = buildWhereCondition(predicate, condition, { resolveLanguage, varIndex: conditions.length });
193
+ const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
184
194
  if (cond) {
185
195
  conditions.push(cond);
186
196
  }
@@ -104,20 +104,38 @@ interpretationHint) {
104
104
  name: propName,
105
105
  path: propMeta.through,
106
106
  };
107
- // Determine datatype from initial value or resolveLanguage
108
- if (propMeta.resolveLanguage === "literal") {
109
- propShape.datatype = "xsd://string";
107
+ // Determine datatype from JS field value type; the resolve* options
108
+ // control storage mode (deterministic vs envelope), not scalar type.
109
+ // A value stored on the literal language (deterministic or envelope,
110
+ // i.e. resolveLanguage unset or "literal") gets a string datatype when
111
+ // no initial value pins a more specific type. A custom resolveLanguage
112
+ // yields an expression URI, not a literal.
113
+ //
114
+ // Skip auto-datatype for properties with a custom `getter` — those
115
+ // typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
116
+ // that hops through a link to another instance's URI). Autosetting
117
+ // `sh:datatype xsd:string` there would trip the hydration decode gate
118
+ // and silently transform `literal:string:<hex>` URIs into their inner
119
+ // plain-string form on read. Users who want a getter to return literal
120
+ // values can opt in explicitly by setting `datatype` on the property
121
+ // options (handled below).
122
+ if (propMeta.datatype) {
123
+ // Explicit opt-in from PropertyOptions always wins over inference.
124
+ propShape.datatype = propMeta.datatype;
110
125
  }
111
- else if (propMeta.initial) {
112
- const initialType = typeof obj[propName];
113
- if (initialType === "number") {
114
- propShape.datatype = "xsd://integer";
115
- }
116
- else if (initialType === "boolean") {
117
- propShape.datatype = "xsd://boolean";
118
- }
119
- else if (initialType === "string") {
120
- propShape.datatype = "xsd://string";
126
+ else {
127
+ const isLiteral = propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
128
+ if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
129
+ const initialType = typeof obj[propName];
130
+ if (initialType === "number") {
131
+ propShape.datatype = "xsd://integer";
132
+ }
133
+ else if (initialType === "boolean") {
134
+ propShape.datatype = "xsd://boolean";
135
+ }
136
+ else if (initialType === "string" || isLiteral) {
137
+ propShape.datatype = "xsd://string";
138
+ }
121
139
  }
122
140
  }
123
141
  // Cardinality constraints
@@ -219,8 +237,19 @@ interpretationHint) {
219
237
  name: relName,
220
238
  path: synthesizedPath,
221
239
  };
222
- // Relations typically contain IRIs
223
- relShape.nodeKind = 'IRI';
240
+ // A relation with a declared `datatype` holds encoded literal
241
+ // values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
242
+ // Everything else is a URI relation pointing at another
243
+ // instance. The executor uses `sh:datatype` on hydration to
244
+ // decide whether to decode `literal:<type>:<value>` wire form
245
+ // (yes for literals, no for URIs).
246
+ if (relMeta.datatype) {
247
+ relShape.datatype = relMeta.datatype;
248
+ relShape.nodeKind = 'Literal';
249
+ }
250
+ else {
251
+ relShape.nodeKind = 'IRI';
252
+ }
224
253
  // Encode relation kind so the executor can derive direction and
225
254
  // scalar-vs-collection rendering without consulting the JS class.
226
255
  relShape.relationKind = relMeta.kind;
@@ -235,10 +264,24 @@ interpretationHint) {
235
264
  if (relMeta.filter === false) {
236
265
  relShape.filter = false;
237
266
  }
267
+ // Ordering is declared in the type system so the executor can act on it
268
+ // for every writer, not just this client.
269
+ if (relMeta.ordering) {
270
+ relShape.ordering = relMeta.ordering.strategy;
271
+ }
238
272
  // AD4M-specific metadata
239
273
  if (relMeta.local !== undefined) {
240
274
  relShape.local = relMeta.local;
241
275
  }
276
+ // Per-relation interpretation hint — sentence-level meaning that
277
+ // steers the harness LLM's `_propose_link_child` `predicate` field
278
+ // description. Read back on the Rust side by
279
+ // `ShaclProperty.interpretation_hint` and rendered into the tool
280
+ // schema alongside the predicate URI enum (so `basedOn` reads
281
+ // "prior beliefs this intention derives from", not just "some link").
282
+ if (relMeta.interpretationHint) {
283
+ relShape.interpretationHint = relMeta.interpretationHint;
284
+ }
242
285
  // Adder / Remover actions — only meaningful for relations backed
243
286
  // by a real link predicate. Getter-only relations are read-only.
244
287
  if (relMeta.predicate) {
@@ -375,6 +418,25 @@ interpretationHint) {
375
418
  }
376
419
  shape.addProperty(relShape);
377
420
  }
421
+ // ── Ordering links ─────────────────────────────────────────────────
422
+ // Ordering entries are stored on the *parent*, under one shared predicate,
423
+ // so that reconstruction needs no extra query: they arrive with the
424
+ // instance's own links. That only works if the instance query asks for them,
425
+ // and it builds its predicate filter from the shape's declared paths — so a
426
+ // class owning any ordered collection has to declare the predicate, or the
427
+ // very links the ordering depends on are filtered out of the read that needs
428
+ // them.
429
+ //
430
+ // One entry covers every ordered relation on the class; each entry names the
431
+ // relation it belongs to.
432
+ const hasOrderedRelation = Object.values(allRelationsMeta).some((m) => m.ordering);
433
+ if (hasOrderedRelation) {
434
+ shape.addProperty({
435
+ name: '_collectionOrder',
436
+ path: 'ad4m://collection_order',
437
+ nodeKind: 'IRI',
438
+ });
439
+ }
378
440
  // Always set constructor and destructor actions on the shape, even
379
441
  // when empty. An empty array serialises to `literal:string:[]`
380
442
  // which the Rust executor parses as a valid (no-op) command list,
@@ -32,15 +32,25 @@ export type Order = {
32
32
  [propertyName: string]: "ASC" | "DESC";
33
33
  };
34
34
  /**
35
- * Discriminated union for parent-scoped queries.
35
+ * A named subgraph scope: a parent node + linking predicate.
36
36
  *
37
- * **Model form** (preferred) — predicate auto-resolved from the parent model's
38
- * relation metadata. Use `field` to disambiguate when the parent has multiple
39
- * relations targeting the same child class.
37
+ * Reusable across contexts that need to identify "the subtree under node X
38
+ * linked via predicate P": query-time filtering as a `parent` filter on a
39
+ * `ModelQuery` (the "all Messages belonging to Channel X" case) AND
40
+ * AutoProcessor's `existingScope` / `mintScope` fields — the former
41
+ * constrains dedup lookups; the latter turns each new mint into a child
42
+ * link under the given node.
43
+ *
44
+ * **Model form** (preferred for parent-filter queries) — predicate
45
+ * auto-resolved from the parent model's relation metadata. Use `field` to
46
+ * disambiguate when the parent has multiple relations targeting the same
47
+ * child class. AutoProcessor `mintScope` requires the **Raw form** because
48
+ * only Raw carries an explicit linking predicate; `Model` scopes have no
49
+ * predicate to write.
40
50
  *
41
51
  * **Raw form** — explicit predicate string, no metadata lookup.
42
52
  */
43
- export type ParentScope = {
53
+ export type Scope = {
44
54
  model: typeof Ad4mModel;
45
55
  id: string;
46
56
  field?: string;
@@ -113,7 +123,7 @@ export interface IncludeProjection {
113
123
  export declare function isIncludeProjection(val: unknown): val is IncludeProjection;
114
124
  export type Query = {
115
125
  /** Filter to instances that are the target of a link from a given parent. */
116
- parent?: ParentScope;
126
+ parent?: Scope;
117
127
  properties?: string[];
118
128
  include?: IncludeMap;
119
129
  /**
@@ -272,7 +282,7 @@ export type IncludeExtras<T extends Ad4mModel, I> = I extends Record<string, any
272
282
  } ? (R extends RelationKeysOf<T> ? RelatedModel<T, R>[] : never) : unknown;
273
283
  } : unknown;
274
284
  type StrictTypedQuery<T extends Ad4mModel> = {
275
- parent?: ParentScope;
285
+ parent?: Scope;
276
286
  properties?: PropertyKeysOf<T>[];
277
287
  include?: TypedIncludeMap<T>;
278
288
  includeAll?: boolean;
@@ -323,7 +333,12 @@ export interface PropertyMetadata {
323
333
  readOnly: boolean;
324
334
  /** Initial value if specified */
325
335
  initial?: string;
326
- /** Language for resolution (e.g., "literal") */
336
+ /** Sole selector of storage mode:
337
+ * - unset → deterministic typed literal (fast POS-index
338
+ * path, the default for a plain `@Property()`)
339
+ * - `"literal"` → signed envelope on the built-in literal language
340
+ * - `<custom address>` → expression on that custom language
341
+ */
327
342
  resolveLanguage?: string;
328
343
  /** Custom Prolog getter code */
329
344
  prologGetter?: string;
@@ -352,6 +367,15 @@ export interface RelationMetadata {
352
367
  local?: boolean;
353
368
  /** Link direction: 'forward' for HasMany/HasOne, 'reverse' for BelongsToMany/BelongsToOne */
354
369
  direction?: 'forward' | 'reverse';
370
+ /**
371
+ * CRDT ordering config, when this collection has a user-controlled order.
372
+ *
373
+ * Its presence is what makes a reorder count as a change: for an ordered
374
+ * relation the sequence *is* the state, where an unordered one is a set.
375
+ */
376
+ ordering?: {
377
+ strategy: 'linkedList';
378
+ };
355
379
  /** Target model class thunk for hydration and type filtering */
356
380
  target?: () => any;
357
381
  /**