@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
@@ -169,11 +169,11 @@ export class ModelQueryBuilder {
169
169
  }
170
170
  const field = options?.field;
171
171
  if (typeof modelOrPredicate === 'string') {
172
- // Raw predicate string → raw form of ParentScope
172
+ // Raw predicate string → raw form of Scope
173
173
  this.queryParams.parent = { id, predicate: modelOrPredicate };
174
174
  }
175
175
  else if (typeof modelOrPredicate === 'function') {
176
- // Model class → model form of ParentScope
176
+ // Model class → model form of Scope
177
177
  this.queryParams.parent = { id, model: modelOrPredicate, ...(field && { field }) };
178
178
  }
179
179
  else if (typeof idOrInstance !== 'string') {
@@ -35,6 +35,32 @@ export interface RelationMetadataEntry {
35
35
  * Overrides auto-derived conformance when set.
36
36
  */
37
37
  where?: Where;
38
+ /**
39
+ * SHACL `sh:datatype` for the relation's target values. Set when the
40
+ * relation holds encoded literal values (e.g. `"xsd:string"` for a
41
+ * `HasMany<string>` that stores plain strings). Emitted into SHACL
42
+ * so the executor knows to decode `literal:<type>:<value>` wire form
43
+ * on hydration. Omit for URI relations that point at other model
44
+ * instances — those pass through byte-for-byte.
45
+ */
46
+ datatype?: string;
47
+ /** Hydrate targets as the class each one actually is — see `RelationOptions.polymorphic`. */
48
+ polymorphic?: boolean;
49
+ /** Model classes this relation's polymorphic results can be constructed as. */
50
+ instantiateAs?: () => Ad4mModelLike[];
51
+ /** CRDT ordering config — see `RelationOptions.ordering`. */
52
+ ordering?: {
53
+ strategy: 'linkedList';
54
+ };
55
+ /**
56
+ * Natural-language hint describing what this relation MEANS semantically.
57
+ * Emitted as an `ad4m://interpretation_hint` link on the SHACL property
58
+ * node; read back by the Rust harness and rendered into the
59
+ * `_propose_link_child` tool's `predicate` field description. Mirror of
60
+ * the same field on `RelationOptions` (the decorator arg); this is the
61
+ * memoized registry copy.
62
+ */
63
+ interpretationHint?: string;
38
64
  }
39
65
  /**
40
66
  * Retrieve property metadata for a given class constructor.
@@ -127,7 +153,16 @@ export interface PropertyOptions {
127
153
  */
128
154
  readOnly?: boolean;
129
155
  /**
130
- * The language used to store the property. Can be the default `Literal` Language or a custom language address.
156
+ * The language used to resolve/store the property value — and the sole
157
+ * selector of storage mode. Not defaulted:
158
+ * - unset (the default for a plain `@Property()`) → deterministic
159
+ * typed literal storage (`literal:string:` / `:number:` / `:boolean:` /
160
+ * `:json:` IRIs stored as XSD-typed RDF literals; POS-index friendly).
161
+ * - `"literal"` → the built-in literal language: values go through
162
+ * `expression_create`, producing a signed-envelope URI with
163
+ * author/timestamp/proof (per-value provenance, e.g. Flux message
164
+ * bodies).
165
+ * - a custom language address → `expression_create` on that language.
131
166
  */
132
167
  resolveLanguage?: string;
133
168
  /**
@@ -197,6 +232,16 @@ export interface PropertyOptions {
197
232
  * should set this.
198
233
  */
199
234
  identity?: boolean;
235
+ /**
236
+ * Explicit SHACL `sh:datatype` for the property value. When set, this
237
+ * overrides auto-inference and — importantly — lets custom `getter`
238
+ * properties opt into typed-literal decoding. Auto-inference is disabled
239
+ * for properties with a `getter` (see `shacl-gen.ts`) because such
240
+ * getters typically return URIs; setting `datatype` explicitly declares
241
+ * that this getter returns literal values of the given XSD type
242
+ * (e.g. `"xsd://string"`) and enables the hydration decode gate.
243
+ */
244
+ datatype?: string;
200
245
  }
201
246
  /**
202
247
  * Convenience decorator for defining optional (not required) properties.
@@ -205,7 +250,7 @@ export interface PropertyOptions {
205
250
  *
206
251
  * @description
207
252
  * Equivalent to `@Property` but defaults `required` to `false` and does not
208
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
253
+ * apply any `initial` defaults. Use this when a property
209
254
  * may or may not have a value, and you want full control over its configuration.
210
255
  *
211
256
  * @example
@@ -317,8 +362,7 @@ export interface ModelConfig {
317
362
  * @Model({ name: "Recipe" })
318
363
  * class Recipe extends Ad4mModel {
319
364
  * @Property({
320
- * through: "recipe://name",
321
- * resolveLanguage: "literal"
365
+ * through: "recipe://name"
322
366
  * })
323
367
  * name: string = "";
324
368
  *
@@ -363,7 +407,9 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
363
407
  * Smart defaults (all overridable):
364
408
  * - `required` → `false`
365
409
  * - `readOnly` → `false`
366
- * - `resolveLanguage` → `"literal"`
410
+ * - `resolveLanguage` → unset → deterministic typed literal storage
411
+ * (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
412
+ * value, or a custom language address to resolve through that language.
367
413
  * - `initial` → `undefined` (no link created until a value is explicitly set)
368
414
  *
369
415
  * Properties are optional by default. When a model instance is created without
@@ -396,7 +442,8 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
396
442
  * })
397
443
  * role: string = "";
398
444
  *
399
- * // Optional property with literal resolution
445
+ * // Optional property with signed-envelope literal storage
446
+ * // (per-value provenance)
400
447
  * @Property({
401
448
  * through: "user://bio",
402
449
  * resolveLanguage: "literal"
@@ -409,7 +456,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
409
456
  * @param {string} opts.through - The predicate URI for the property
410
457
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
411
458
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
412
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
459
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
413
460
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
414
461
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
415
462
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
@@ -466,7 +513,7 @@ export declare function Property(opts: PropertyOptions): <T>(target: T, key: key
466
513
  * @param {PropertyOptions} opts - Property configuration
467
514
  * @param {string} opts.through - The predicate URI for the property
468
515
  * @param {string} [opts.initial] - Initial value (if property should have one)
469
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
516
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
470
517
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
471
518
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
472
519
  */
@@ -482,15 +529,34 @@ export interface RelationOptions {
482
529
  */
483
530
  through?: string;
484
531
  /** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations.
485
- * Cannot be combined with `getter`. */
532
+ * Combines with `getter`, where it names the class the traversal's values hydrate into. */
486
533
  target?: () => Ad4mModelLike;
487
534
  /**
488
535
  * Custom getter to resolve the relation values. Use this for custom graph traversals.
489
536
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
490
537
  * Example: "SELECT ?target WHERE { ?target <flux://has_reply> <Base> . }"
491
538
  *
492
- * Mutually exclusive with `through` and `target`. When `getter` is provided the
493
- * relation is read-only (no adder/remover actions are generated).
539
+ * Mutually exclusive with `through` — a getter replaces link-based resolution,
540
+ * so there is no predicate to add to or remove from. When `getter` is provided
541
+ * the relation is read-only (no adder/remover actions are generated).
542
+ *
543
+ * **Combines with `target`**, which names the class the traversal's values
544
+ * hydrate into — without it `include` has no shape to resolve and the relation
545
+ * can only return bare URIs. Also combines with `where`, applied as a
546
+ * post-getter filter against the target class.
547
+ *
548
+ * @example Traversing a reified edge — a connection stored as a record rather
549
+ * than a predicate, so no `through` can express it:
550
+ * ```typescript
551
+ * @HasMany({
552
+ * getter: `SELECT ?target WHERE {
553
+ * ?citation <paper://cites_from> <Base> .
554
+ * ?citation <paper://cites_to> ?target .
555
+ * }`,
556
+ * target: () => Paper,
557
+ * })
558
+ * cited: Paper[] = [];
559
+ * ```
494
560
  */
495
561
  getter?: string;
496
562
  /** Whether the link is stored locally (not shared on the network) */
@@ -511,7 +577,8 @@ export interface RelationOptions {
511
577
  * auto-derived from the target shape (flags + required properties).
512
578
  * Providing `where` overrides this auto-derivation.
513
579
  *
514
- * Mutually exclusive with `getter` and `filter: false`.
580
+ * Mutually exclusive with `filter: false`. Combines with `getter`, where it
581
+ * is applied as a post-getter filter against the target class.
515
582
  *
516
583
  * @example
517
584
  * ```typescript
@@ -523,6 +590,126 @@ export interface RelationOptions {
523
590
  * ```
524
591
  */
525
592
  where?: Where;
593
+ /**
594
+ * SHACL `sh:datatype` for the relation's target values. Set when the
595
+ * relation holds encoded literal values (e.g. `"xsd:string"` for a
596
+ * `HasMany<string>` that stores plain strings). The executor uses
597
+ * this to decode `literal:<type>:<value>` wire form on hydration.
598
+ * Omit for URI relations that point at other model instances.
599
+ *
600
+ * @example
601
+ * ```typescript
602
+ * @HasMany({ through: "run://source", datatype: "xsd:string" })
603
+ * sources: string[] = [];
604
+ * ```
605
+ */
606
+ datatype?: string;
607
+ /**
608
+ * Hydrate each target as the class it actually **is**, rather than as the
609
+ * class this relation declares.
610
+ *
611
+ * A heterogeneous relation has no single right target. Declaring the base
612
+ * class loses every subclass property — the executor hydrates against the
613
+ * shape it is given, so an `ImagePost` read as a `Post` arrives with its own
614
+ * fields simply absent, not merely mislabelled. Declaring nothing leaves
615
+ * `include` with no shape to resolve at all.
616
+ *
617
+ * With this set, the targets are classified, grouped by concrete class, and
618
+ * hydrated against their own shapes — one query per distinct class present,
619
+ * not per instance.
620
+ *
621
+ * Pair with `instantiateAs` so the results become instances of the right
622
+ * model class rather than plain objects.
623
+ *
624
+ * @example
625
+ * ```typescript
626
+ * @HasMany({
627
+ * through: "we://children",
628
+ * polymorphic: true,
629
+ * instantiateAs: () => [TextBlock, ImageBlock],
630
+ * })
631
+ * children: Post[] = [];
632
+ * ```
633
+ */
634
+ polymorphic?: boolean;
635
+ /**
636
+ * The model classes a `polymorphic` result may be constructed as.
637
+ *
638
+ * Classification happens in the executor, structurally — there is no
639
+ * `rdf:type` triple to read, so a target's class is derived from the flags
640
+ * and required properties it carries. What cannot cross the wire is the
641
+ * TypeScript constructor, so this names the classes this side can build.
642
+ * `@Model` already records each class's name on the class itself, so the
643
+ * name → class mapping is derived from the list rather than restated
644
+ * alongside it.
645
+ *
646
+ * **This is advisory, not a constraint.** It never narrows what the query
647
+ * returns and never excludes a target: a class missing from the list arrives
648
+ * as plain JSON carrying its class name, so partial knowledge degrades
649
+ * instead of failing. Declaring what this call site can *construct* is a
650
+ * different statement from declaring what the relation may *contain* — a
651
+ * heterogeneous relation is open by definition, and a list that silently
652
+ * dropped unrecognised members would defeat the point of reading it
653
+ * polymorphically at all. Constraining a read to particular classes belongs
654
+ * in the query, not here.
655
+ *
656
+ * A thunk rather than an array, for the same reason `target` is one: it is
657
+ * evaluated at query time, so a class defined later in a circular import
658
+ * graph still resolves.
659
+ */
660
+ instantiateAs?: () => Ad4mModelLike[];
661
+ /**
662
+ * Give this collection a user-controlled order that survives concurrent edits.
663
+ *
664
+ * A `@HasMany` is a set of links, and hydration sorts them by link timestamp.
665
+ * That is right for an append-only collection — a transcript, a message
666
+ * thread — where timestamp order *is* the order. It cannot express a sequence
667
+ * somebody chose: a kanban column, a playlist, the blocks of a post.
668
+ *
669
+ * **Declaration only, for now.** Setting this emits `ad4m://ordering` on the
670
+ * property shape, where the executor reads it back — but no read or write
671
+ * path acts on it yet, so a relation declaring it still hydrates by link
672
+ * timestamp exactly as one that does not. Wiring save and hydration to the
673
+ * declaration is the next change; nothing about how you write the relation
674
+ * will change when it lands — assign the array in the order you want and
675
+ * save.
676
+ *
677
+ * Ordering is declared in the type system, rather than passed per query, so
678
+ * that *every* writer gets it once it is wired: the ORM, MCP agents, raw
679
+ * WS-RPC callers, another app sharing the neighbourhood. Implemented
680
+ * client-side it would order only what this client wrote.
681
+ *
682
+ * @example
683
+ * ```typescript
684
+ * @HasMany(() => Task, {
685
+ * through: "kanban://has_task",
686
+ * ordering: { strategy: "linkedList" },
687
+ * })
688
+ * tasks: Task[] = [];
689
+ * ```
690
+ */
691
+ ordering?: {
692
+ strategy: 'linkedList';
693
+ };
694
+ /**
695
+ * Natural-language hint describing what this relation MEANS semantically —
696
+ * the sentence-level rationale for when to use it, not just its structural
697
+ * shape. Emitted as an `ad4m://interpretation_hint` link on the SHACL
698
+ * property node; read back by the Rust harness (`ClassProposeShape.
699
+ * relations[N].hint`) and rendered into the `_propose_link_child` tool's
700
+ * `predicate` field description so the LLM knows which relation applies
701
+ * to which situation instead of guessing from the predicate name alone.
702
+ *
703
+ * @example
704
+ * ```typescript
705
+ * @HasMany(() => Belief, {
706
+ * through: "ns://basedOn",
707
+ * interpretationHint: "The prior beliefs this intention derives from.",
708
+ * })
709
+ * basedOn: Belief[] = [];
710
+ * ```
711
+ */
712
+ interpretationHint?: string;
526
713
  }
527
714
  /**
528
715
  * Utility type that describes the auto-generated helper methods for a HasMany
@@ -206,7 +206,7 @@ function applyPropertyMetadata(opts) {
206
206
  *
207
207
  * @description
208
208
  * Equivalent to `@Property` but defaults `required` to `false` and does not
209
- * apply `resolveLanguage` or `initial` defaults. Use this when a property
209
+ * apply any `initial` defaults. Use this when a property
210
210
  * may or may not have a value, and you want full control over its configuration.
211
211
  *
212
212
  * @example
@@ -329,8 +329,7 @@ export function Flag(opts) {
329
329
  * @Model({ name: "Recipe" })
330
330
  * class Recipe extends Ad4mModel {
331
331
  * @Property({
332
- * through: "recipe://name",
333
- * resolveLanguage: "literal"
332
+ * through: "recipe://name"
334
333
  * })
335
334
  * name: string = "";
336
335
  *
@@ -387,7 +386,9 @@ export function Model(opts) {
387
386
  * Smart defaults (all overridable):
388
387
  * - `required` → `false`
389
388
  * - `readOnly` → `false`
390
- * - `resolveLanguage` → `"literal"`
389
+ * - `resolveLanguage` → unset → deterministic typed literal storage
390
+ * (the perf default). Set `resolveLanguage: "literal"` for a signed-envelope
391
+ * value, or a custom language address to resolve through that language.
391
392
  * - `initial` → `undefined` (no link created until a value is explicitly set)
392
393
  *
393
394
  * Properties are optional by default. When a model instance is created without
@@ -420,7 +421,8 @@ export function Model(opts) {
420
421
  * })
421
422
  * role: string = "";
422
423
  *
423
- * // Optional property with literal resolution
424
+ * // Optional property with signed-envelope literal storage
425
+ * // (per-value provenance)
424
426
  * @Property({
425
427
  * through: "user://bio",
426
428
  * resolveLanguage: "literal"
@@ -433,18 +435,22 @@ export function Model(opts) {
433
435
  * @param {string} opts.through - The predicate URI for the property
434
436
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
435
437
  * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
436
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
438
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
437
439
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
438
440
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
439
441
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
440
442
  */
441
443
  export function Property(opts) {
442
444
  const required = opts.required ?? false;
445
+ // `resolveLanguage` is intentionally NOT defaulted here.
446
+ // The effective storage mode is derived from what the user explicitly set:
447
+ // - unset → deterministic typed literal (the perf default)
448
+ // - "literal" → signed literal envelope (per-value provenance)
449
+ // - <custom address> → expression on that custom language
443
450
  return applyPropertyMetadata({
444
451
  ...opts,
445
452
  required,
446
453
  readOnly: opts.readOnly ?? false,
447
- resolveLanguage: opts.resolveLanguage ?? "literal",
448
454
  initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
449
455
  });
450
456
  }
@@ -499,7 +505,7 @@ export function Property(opts) {
499
505
  * @param {PropertyOptions} opts - Property configuration
500
506
  * @param {string} opts.through - The predicate URI for the property
501
507
  * @param {string} [opts.initial] - Initial value (if property should have one)
502
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
508
+ * @param {string} [opts.resolveLanguage] - Value-resolution language: unset (deterministic typed literal, the perf default), "literal" (signed envelope), or a custom language address
503
509
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
504
510
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
505
511
  */
@@ -520,35 +526,57 @@ function resolveRelationArgs(first, second) {
520
526
  const opts = typeof first === 'function'
521
527
  ? { ...(second || {}), target: first }
522
528
  : first;
523
- // getter is mutually exclusive with through, target, and where
529
+ // `where` and `filter: false` contradict each other on every relation,
530
+ // getter-backed ones included — checked before the getter path returns.
531
+ if (opts.where && opts.filter === false) {
532
+ throw new Error('Relation decorator: `where` and `filter: false` are contradictory. ' +
533
+ '`where` adds filtering constraints; `filter: false` disables filtering.');
534
+ }
535
+ // getter is mutually exclusive with through
524
536
  if (opts.getter) {
525
537
  if (opts.through) {
526
538
  throw new Error('Relation decorator: `getter` and `through` are mutually exclusive. ' +
527
539
  'Use `getter` alone for custom read-only relations, or `through` ' +
528
540
  '(with optional `target`) for standard link-based relations.');
529
541
  }
530
- if (opts.target) {
531
- throw new Error('Relation decorator: `getter` and `target` are mutually exclusive. ' +
532
- '`target` auto-generates a conformance getter from the model shape; ' +
533
- 'providing both is contradictory.');
534
- }
535
- if (opts.where) {
536
- throw new Error('Relation decorator: `where` and `getter` are mutually exclusive. ' +
537
- 'Use `where` for DSL-based filtering, or `getter` for raw getter expression.');
538
- }
542
+ // `target` and `where` are NOT mutually exclusive with `getter`.
543
+ //
544
+ // `target` does two separable jobs: it auto-derives a conformance
545
+ // getter, and it names the class the relation's values hydrate into.
546
+ // Only the first conflicts with an explicit getter, and `buildSHACL`
547
+ // already resolves that on its own — an explicit getter wins the getter
548
+ // slot, while `sh:class` / `ad4m:targetClassName` are emitted from
549
+ // `target` independently.
550
+ //
551
+ // Refusing the pair cost the one thing a custom getter is for. A getter
552
+ // expresses a traversal the link-shaped DSL cannot — most usefully
553
+ // through a reified edge, where the connection is a record rather than
554
+ // a predicate:
555
+ //
556
+ // @HasMany({
557
+ // getter: "SELECT ?target WHERE { \
558
+ // ?citation <paper://cites_from> <Base> . \
559
+ // ?citation <paper://cites_to> ?target . }",
560
+ // target: () => Paper,
561
+ // })
562
+ // cited: Paper[] = [];
563
+ //
564
+ // Without `target` the relation has no target class, so `include` on it
565
+ // resolves a shape named "" and fails — leaving a traversal that can
566
+ // only ever return bare URIs. With it, the values hydrate like any other
567
+ // relation, because getters are evaluated before include resolution.
568
+ //
569
+ // `where` is the same story: the executor applies post-getter where
570
+ // filters specifically to getter-backed relations
571
+ // (`apply_where_filter_to_relation`), and emitting `wherePredicates`
572
+ // needs `target` to resolve the target's metadata — so the runtime is
573
+ // built for all three together and only this check said otherwise.
539
574
  return opts;
540
575
  }
541
576
  // Default predicate when not provided
542
577
  if (!opts.through) {
543
578
  opts.through = 'ad4m://has_child';
544
579
  }
545
- // where validation
546
- if (opts.where) {
547
- if (opts.filter === false) {
548
- throw new Error('Relation decorator: `where` and `filter: false` are contradictory. ' +
549
- '`where` adds filtering constraints; `filter: false` disables filtering.');
550
- }
551
- }
552
580
  return opts;
553
581
  }
554
582
  export function HasMany(first, second) {
@@ -567,6 +595,11 @@ export function HasMany(first, second) {
567
595
  ...(opts.getter && { getter: opts.getter }),
568
596
  ...(opts.filter !== undefined && { filter: opts.filter }),
569
597
  ...(opts.where && { where: opts.where }),
598
+ ...(opts.datatype && { datatype: opts.datatype }),
599
+ ...(opts.polymorphic && { polymorphic: opts.polymorphic }),
600
+ ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
601
+ ...(opts.ordering && { ordering: opts.ordering }),
602
+ ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
570
603
  };
571
604
  const relKey = key;
572
605
  // Only add mutation methods when a predicate is available
@@ -600,6 +633,11 @@ export function HasOne(first, second) {
600
633
  local: opts.local,
601
634
  ...(opts.filter !== undefined && { filter: opts.filter }),
602
635
  ...(opts.where && { where: opts.where }),
636
+ ...(opts.datatype && { datatype: opts.datatype }),
637
+ ...(opts.polymorphic && { polymorphic: opts.polymorphic }),
638
+ ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
639
+ ...(opts.ordering && { ordering: opts.ordering }),
640
+ ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
603
641
  };
604
642
  const relKey = key;
605
643
  if (opts.through) {
@@ -609,15 +647,23 @@ export function HasOne(first, second) {
609
647
  readOnly: false,
610
648
  local: opts.local,
611
649
  })(target, key);
612
- // Add prototype methods for add/remove/set (mirroring @HasMany)
613
- target[`add${capitalize(relKey)}`] = async function (arg) {
614
- return this.addRelationValue(relKey, arg);
650
+ // Add prototype methods for add/remove/set (mirroring @HasMany).
651
+ //
652
+ // `batchId` is part of that mirroring: without it a to-one link
653
+ // cannot join a write group, so anything that creates a record and
654
+ // then points it at something has to commit twice and every
655
+ // subscriber sees the state in between — a record whose to-one
656
+ // relation is still empty. Anything rendering from a subscription
657
+ // therefore has a frame in which the record exists and points at
658
+ // nothing.
659
+ target[`add${capitalize(relKey)}`] = async function (arg, batchId) {
660
+ return this.addRelationValue(relKey, arg, batchId);
615
661
  };
616
- target[`remove${capitalize(relKey)}`] = async function (arg) {
617
- return this.removeRelationValue(relKey, arg);
662
+ target[`remove${capitalize(relKey)}`] = async function (arg, batchId) {
663
+ return this.removeRelationValue(relKey, arg, batchId);
618
664
  };
619
- target[`set${capitalize(relKey)}`] = async function (arg) {
620
- return this.setRelationValues(relKey, arg);
665
+ target[`set${capitalize(relKey)}`] = async function (arg, batchId) {
666
+ return this.setRelationValues(relKey, arg, batchId);
621
667
  };
622
668
  }
623
669
  else {
@@ -640,6 +686,11 @@ export function BelongsToOne(first, second) {
640
686
  local: opts.local,
641
687
  ...(opts.filter !== undefined && { filter: opts.filter }),
642
688
  ...(opts.where && { where: opts.where }),
689
+ ...(opts.datatype && { datatype: opts.datatype }),
690
+ ...(opts.polymorphic && { polymorphic: opts.polymorphic }),
691
+ ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
692
+ ...(opts.ordering && { ordering: opts.ordering }),
693
+ ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
643
694
  };
644
695
  if (opts.through) {
645
696
  // Read-only property (the owning side manages the link)
@@ -669,6 +720,11 @@ export function BelongsToMany(first, second) {
669
720
  ...(opts.getter && { getter: opts.getter }),
670
721
  ...(opts.filter !== undefined && { filter: opts.filter }),
671
722
  ...(opts.where && { where: opts.where }),
723
+ ...(opts.datatype && { datatype: opts.datatype }),
724
+ ...(opts.polymorphic && { polymorphic: opts.polymorphic }),
725
+ ...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
726
+ ...(opts.ordering && { ordering: opts.ordering }),
727
+ ...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
672
728
  };
673
729
  // @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
674
730
  // prototype methods. Mutation must go through the owning side's @HasMany decorator.
@@ -238,13 +238,7 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
238
238
  }
239
239
  else {
240
240
  // Handle regular properties
241
- let resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
242
- // If no specific resolveLanguage for this property, use the global one
243
- if (!resolveLanguage && options.resolveLanguage) {
244
- resolveLanguage = options.resolveLanguage;
245
- }
246
241
  const local = getPropertyOption(propertyName, propertySchema, options, 'local');
247
- // Determine readOnly: check PropertyOptions first, then x-ad4m.writable (inverted) for JSON Schema wire format
248
242
  let readOnly = getPropertyOption(propertyName, propertySchema, options, 'readOnly');
249
243
  if (readOnly === undefined) {
250
244
  const xWritable = propertySchema["x-ad4m"]?.writable;
@@ -252,22 +246,14 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
252
246
  }
253
247
  const writable = !readOnly;
254
248
  let initial = getPropertyOption(propertyName, propertySchema, options, 'initial');
255
- // Handle nested objects by serializing to JSON
256
- if (isObjectType(propertySchema) && !resolveLanguage) {
257
- resolveLanguage = 'literal';
249
+ // Not defaulted — absence means "deterministic typed literal" (the
250
+ // perf default); an explicit `resolveLanguage: "literal"` selects the
251
+ // signed-envelope path; any other value selects a custom language.
252
+ // See effectiveLiteralStorage().
253
+ const resolveLanguage = getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
254
+ if (isObjectType(propertySchema)) {
258
255
  console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
259
256
  }
260
- // Ensure numeric properties use literal language for correct typing
261
- if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
262
- resolveLanguage = 'literal';
263
- }
264
- // Default resolveLanguage to 'literal' for all remaining property types,
265
- // matching the @Property decorator behaviour. Without this, string values
266
- // stored as literal: URLs are returned unparsed.
267
- if (resolveLanguage === undefined || resolveLanguage === null) {
268
- resolveLanguage = 'literal';
269
- }
270
- // If property is required, ensure it has an initial value
271
257
  if (isRequired && !initial) {
272
258
  if (isObjectType(propertySchema)) {
273
259
  initial = 'literal:json:{}';
@@ -280,7 +266,7 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
280
266
  through: predicate,
281
267
  required: isRequired,
282
268
  writable: writable,
283
- ...(resolveLanguage && { resolveLanguage }),
269
+ ...(resolveLanguage !== undefined && { resolveLanguage }),
284
270
  ...(local !== undefined && { local }),
285
271
  ...(initial && { initial })
286
272
  };
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Types for the perspective model manifest — a human-readable, AI-friendly summary
3
+ * of all Ad4mModel-compatible classes defined in a perspective's SHACL shapes.
4
+ *
5
+ * Used by `PerspectiveProxy.getModelManifest()` and consumed by WE's AI context
6
+ * injection (`formatManifestForPrompt`) to describe external perspective models
7
+ * to the schema-generation AI.
8
+ *
9
+ * @module
10
+ */
11
+ /** Normalised description of a single property on a model class. */
12
+ export interface ModelManifestProperty {
13
+ /** Property name as declared in the SHACL shape (e.g. "name", "body", "participants"). */
14
+ name: string;
15
+ /** The exact RDF predicate URI (e.g. "flux://has_name"). */
16
+ predicate: string;
17
+ /** Normalised scalar type; inferred from xsd:/sh: datatype + nodeKind. */
18
+ type: 'string' | 'number' | 'boolean' | 'uri';
19
+ /** `true` when maxCount is absent or > 1 (i.e. returned as an array). */
20
+ isCollection: boolean;
21
+ /** `true` when minCount >= 1. */
22
+ required: boolean;
23
+ writable: boolean;
24
+ /** AD4M language used to resolve the value (e.g. "literal"). */
25
+ resolveLanguage?: string;
26
+ /**
27
+ * Local name of the related model class when this is a typed relation property.
28
+ * Derived from `SHACLPropertyShape.class` by stripping the URI prefix.
29
+ * E.g. `flux://Message` → `"Message"`.
30
+ */
31
+ relatedModel?: string;
32
+ }
33
+ /** Normalised description of a single model class stored in a perspective. */
34
+ export interface ModelManifestEntry {
35
+ /** Class name — usable directly as the `model` field in a `$query` token. */
36
+ name: string;
37
+ /** The SHACL `targetClass` URI (e.g. "flux://Channel"). */
38
+ targetClass: string;
39
+ /** All data properties (flag/hasValue properties are excluded). */
40
+ properties: ModelManifestProperty[];
41
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Types for the perspective model manifest — a human-readable, AI-friendly summary
3
+ * of all Ad4mModel-compatible classes defined in a perspective's SHACL shapes.
4
+ *
5
+ * Used by `PerspectiveProxy.getModelManifest()` and consumed by WE's AI context
6
+ * injection (`formatManifestForPrompt`) to describe external perspective models
7
+ * to the schema-generation AI.
8
+ *
9
+ * @module
10
+ */
11
+ export {};
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Shared query helpers used by both the Prolog and SPARQL query pipelines.
3
3
  */
4
- import type { ParentScope } from "./types";
4
+ import type { Scope } from "./types";
5
5
  /**
6
6
  * Resolves the predicate for a parent query.
7
7
  *
@@ -11,4 +11,4 @@ import type { ParentScope } from "./types";
11
11
  * - With `field`: direct key lookup
12
12
  * - Without `field`: scan for a relation whose `target()` matches `childCtor`
13
13
  */
14
- export declare function resolveParentPredicate(parent: ParentScope, childCtor: Function): string;
14
+ export declare function resolveParentPredicate(parent: Scope, childCtor: Function): string;