@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
@@ -17,6 +17,7 @@ import {
17
17
  BelongsToOne,
18
18
  BelongsToMany,
19
19
  } from "./decorators";
20
+ import { SHACLShape } from "../shacl/SHACLShape";
20
21
 
21
22
  function flatten(
22
23
  shape: any,
@@ -180,7 +181,7 @@ describe("Decorators → SHACL writer round-trip", () => {
180
181
  it("emits scalar property predicates", () => {
181
182
  @Model({ name: "Profile" })
182
183
  class Profile extends Ad4mModel {
183
- @Property({ through: "ns://name", resolveLanguage: "literal" })
184
+ @Property({ through: "ns://name" })
184
185
  name: string = "";
185
186
  }
186
187
 
@@ -190,9 +191,11 @@ describe("Decorators → SHACL writer round-trip", () => {
190
191
  expect(findLinkTarget(links, "ns://Profile.name", "sh://path")).toBe(
191
192
  "ns://name",
192
193
  );
194
+ // A bare @Property is deterministic-literal by default — no
195
+ // resolveLanguage link is emitted.
193
196
  expect(
194
197
  findLinkTarget(links, "ns://Profile.name", "ad4m://resolveLanguage"),
195
- ).toBe("literal:string:literal");
198
+ ).toBeUndefined();
196
199
  });
197
200
 
198
201
  it("emits ad4m://interpretation_hint on the class shape and per property", () => {
@@ -232,6 +235,59 @@ describe("Decorators → SHACL writer round-trip", () => {
232
235
  ).toBeUndefined();
233
236
  });
234
237
 
238
+ it("emits ad4m://interpretation_hint on relation properties", () => {
239
+ // Relation-level interpretation hints (RelationOptions.interpretationHint)
240
+ // are read by the Rust harness's `ShaclProperty.interpretation_hint` and
241
+ // rendered into the `_propose_link_child` predicate-field description so
242
+ // the LLM knows what each relation MEANS semantically, not just that it
243
+ // exists. Regression against the follow-up-branch scope creep: pulled
244
+ // into PR #911 per Nico's 2026-08-24 ask.
245
+ @Model({ name: "Intention" })
246
+ class Intention extends Ad4mModel {
247
+ @Property({
248
+ through: "ns://title",
249
+ required: true,
250
+ interpretationHint: "Imperative statement of intent.",
251
+ })
252
+ title: string = "";
253
+
254
+ @HasMany(() => Belief, {
255
+ through: "ns://basedOn",
256
+ interpretationHint:
257
+ "The prior beliefs this intention derives from.",
258
+ })
259
+ basedOn: Belief[] = [];
260
+
261
+ @HasMany(() => Belief, { through: "ns://contradicts" })
262
+ contradicts: Belief[] = [];
263
+ }
264
+ @Model({ name: "Belief" })
265
+ class Belief extends Ad4mModel {
266
+ @Property({ through: "ns://title", required: true }) title: string = "";
267
+ }
268
+
269
+ const { shape } = Intention.generateSHACL();
270
+ const links = flatten(shape);
271
+
272
+ // Named relation with a hint → link present on the relation's property
273
+ // node with the hint text.
274
+ expect(
275
+ findLinkTarget(links, "ns://Intention.basedOn", "ad4m://interpretation_hint"),
276
+ ).toBe(
277
+ "literal:string:The prior beliefs this intention derives from.",
278
+ );
279
+
280
+ // Named relation WITHOUT a hint → no interpretation_hint link (the
281
+ // scalar-property "no hint = no link" path is what relations follow too).
282
+ expect(
283
+ findLinkTarget(
284
+ links,
285
+ "ns://Intention.contradicts",
286
+ "ad4m://interpretation_hint",
287
+ ),
288
+ ).toBeUndefined();
289
+ });
290
+
235
291
  it("round-trips interpretationHint through toJSON/fromJSON", () => {
236
292
  @Model({
237
293
  name: "Task",
@@ -270,4 +326,80 @@ describe("Decorators → SHACL writer round-trip", () => {
270
326
  "Imperative summary of the work.",
271
327
  );
272
328
  });
329
+
330
+ it("round-trips ordering through toLinks/fromLinks", () => {
331
+ @Model({ name: "OrderedItem" })
332
+ class OrderedItem extends Ad4mModel {}
333
+
334
+ @Model({ name: "OrderedHolder" })
335
+ class OrderedHolder extends Ad4mModel {
336
+ @HasMany({
337
+ through: "ns://ordered",
338
+ target: () => OrderedItem,
339
+ ordering: { strategy: "linkedList" },
340
+ })
341
+ ordered: string[] = [];
342
+ }
343
+
344
+ const { shape } = OrderedHolder.generateSHACL();
345
+ const links = shape.toLinks();
346
+
347
+ // Pin the wire format itself. `ordering` is the one relation field the
348
+ // read path recovers by stripping a prefix off the target rather than by
349
+ // parsing a typed literal, so a change to how the writer spells it would
350
+ // otherwise surface as the executor silently seeing no strategy.
351
+ expect(
352
+ findLinkTarget(
353
+ flatten(shape),
354
+ "ns://OrderedHolder.ordered",
355
+ "ad4m://ordering",
356
+ ),
357
+ ).toBe("literal:string:linkedList");
358
+
359
+ const rebuilt = SHACLShape.fromLinks(links, shape.nodeShapeUri);
360
+ const rebuiltProp = rebuilt.properties.find(
361
+ (p: any) => p.name === "ordered",
362
+ );
363
+ expect(rebuiltProp?.ordering).toBe("linkedList");
364
+ });
365
+
366
+ it("round-trips ordering through toJSON/fromJSON", () => {
367
+ @Model({ name: "JsonOrderedItem" })
368
+ class JsonOrderedItem extends Ad4mModel {}
369
+
370
+ @Model({ name: "JsonOrderedHolder" })
371
+ class JsonOrderedHolder extends Ad4mModel {
372
+ @HasMany({
373
+ through: "ns://ordered",
374
+ target: () => JsonOrderedItem,
375
+ ordering: { strategy: "linkedList" },
376
+ })
377
+ ordered: string[] = [];
378
+
379
+ @HasMany({ through: "ns://plain", target: () => JsonOrderedItem })
380
+ plain: string[] = [];
381
+ }
382
+
383
+ const { shape } = JsonOrderedHolder.generateSHACL();
384
+
385
+ // `toJSON` — not `toLinks` — is what `ensureSubjectClass` ships to the
386
+ // backend, which turns it into the `ad4m://ordering` link the executor
387
+ // reads the strategy back from. A declaration dropped here is inert
388
+ // end to end however faithfully `toLinks` spells it: the setter writes
389
+ // no ordering entries and hydration never reorders.
390
+ const json: any = shape.toJSON();
391
+ const orderedProp = json.properties.find((p: any) => p.name === "ordered");
392
+ expect(orderedProp?.ordering).toBe("linkedList");
393
+
394
+ const plainProp = json.properties.find((p: any) => p.name === "plain");
395
+ expect(plainProp?.ordering).toBeUndefined();
396
+
397
+ const rebuilt = SHACLShape.fromJSON(json);
398
+ expect(
399
+ rebuilt.properties.find((p: any) => p.name === "ordered")?.ordering,
400
+ ).toBe("linkedList");
401
+ expect(
402
+ rebuilt.properties.find((p: any) => p.name === "plain")?.ordering,
403
+ ).toBeUndefined();
404
+ });
273
405
  });
@@ -47,15 +47,25 @@ export type Where = {
47
47
  export type Order = { [propertyName: string]: "ASC" | "DESC" };
48
48
 
49
49
  /**
50
- * Discriminated union for parent-scoped queries.
50
+ * A named subgraph scope: a parent node + linking predicate.
51
51
  *
52
- * **Model form** (preferred) — predicate auto-resolved from the parent model's
53
- * relation metadata. Use `field` to disambiguate when the parent has multiple
54
- * relations targeting the same child class.
52
+ * Reusable across contexts that need to identify "the subtree under node X
53
+ * linked via predicate P": query-time filtering as a `parent` filter on a
54
+ * `ModelQuery` (the "all Messages belonging to Channel X" case) AND
55
+ * AutoProcessor's `existingScope` / `mintScope` fields — the former
56
+ * constrains dedup lookups; the latter turns each new mint into a child
57
+ * link under the given node.
58
+ *
59
+ * **Model form** (preferred for parent-filter queries) — predicate
60
+ * auto-resolved from the parent model's relation metadata. Use `field` to
61
+ * disambiguate when the parent has multiple relations targeting the same
62
+ * child class. AutoProcessor `mintScope` requires the **Raw form** because
63
+ * only Raw carries an explicit linking predicate; `Model` scopes have no
64
+ * predicate to write.
55
65
  *
56
66
  * **Raw form** — explicit predicate string, no metadata lookup.
57
67
  */
58
- export type ParentScope =
68
+ export type Scope =
59
69
  | { model: typeof Ad4mModel; id: string; field?: string }
60
70
  | { id: string; predicate: string };
61
71
 
@@ -129,7 +139,7 @@ export function isIncludeProjection(val: unknown): val is IncludeProjection {
129
139
 
130
140
  export type Query = {
131
141
  /** Filter to instances that are the target of a link from a given parent. */
132
- parent?: ParentScope;
142
+ parent?: Scope;
133
143
  properties?: string[];
134
144
  include?: IncludeMap;
135
145
  /**
@@ -345,7 +355,7 @@ export type IncludeExtras<T extends Ad4mModel, I> =
345
355
  // ---- Typed Query -------------------------------------------------------------
346
356
 
347
357
  type StrictTypedQuery<T extends Ad4mModel> = {
348
- parent?: ParentScope;
358
+ parent?: Scope;
349
359
  properties?: PropertyKeysOf<T>[];
350
360
  include?: TypedIncludeMap<T>;
351
361
  includeAll?: boolean;
@@ -402,7 +412,12 @@ export interface PropertyMetadata {
402
412
  readOnly: boolean;
403
413
  /** Initial value if specified */
404
414
  initial?: string;
405
- /** Language for resolution (e.g., "literal") */
415
+ /** Sole selector of storage mode:
416
+ * - unset → deterministic typed literal (fast POS-index
417
+ * path, the default for a plain `@Property()`)
418
+ * - `"literal"` → signed envelope on the built-in literal language
419
+ * - `<custom address>` → expression on that custom language
420
+ */
406
421
  resolveLanguage?: string;
407
422
  /** Custom Prolog getter code */
408
423
  prologGetter?: string;
@@ -432,6 +447,13 @@ export interface RelationMetadata {
432
447
  local?: boolean;
433
448
  /** Link direction: 'forward' for HasMany/HasOne, 'reverse' for BelongsToMany/BelongsToOne */
434
449
  direction?: 'forward' | 'reverse';
450
+ /**
451
+ * CRDT ordering config, when this collection has a user-controlled order.
452
+ *
453
+ * Its presence is what makes a reorder count as a change: for an ordered
454
+ * relation the sequence *is* the state, where an unordered one is a set.
455
+ */
456
+ ordering?: { strategy: 'linkedList' };
435
457
  /** Target model class thunk for hydration and type filtering */
436
458
  target?: () => any;
437
459
  /**
@@ -3,7 +3,76 @@
3
3
  // `AutoProcessorConfig` / `auto_processor::events::AutoProcessorEvent`
4
4
  // (serde `camelCase`).
5
5
 
6
- /** One step in an auto-processor pass (serde camelCase of the Rust enum). */
6
+ /**
7
+ * Raw form of `Scope` (parent node + linking predicate) — the only variant
8
+ * the WebSocket auto-processor config accepts. `Scope`'s model form
9
+ * (`{ model: typeof Ad4mModel, id, field? }`) references a JS class
10
+ * constructor, which JSON.stringify silently drops, so the executor would
11
+ * receive `{ id }` and the scope would be unresolvable. Client callers who
12
+ * hold a model class should resolve its predicate via
13
+ * `ModelQueryBuilder.buildParentScope()` first and pass the result here.
14
+ */
15
+ export type RawScope = { id: string; predicate: string };
16
+
17
+ /**
18
+ * One step in an auto-processor pass (serde camelCase of the Rust enum).
19
+ *
20
+ * ## Lifecycle (winning peer, emitDebugEvents: true)
21
+ *
22
+ * A pass on the winning executor emits, in order:
23
+ *
24
+ * 1. `batchReady` — debounced batch reached threshold, pass starting
25
+ * 2. `claimed` — this executor won the `try_claim`
26
+ * 3. `gatheringTranscript` — pulling the batch's transcript turns
27
+ * 4. `runningInterpretation` — about to invoke the LLM
28
+ * 5. `llmRequestSent` — prompt built + dispatched; carries `llmInput`
29
+ * (only when `emitDebugEvents: true`)
30
+ * 6. `llmResponseReceived` — LLM response arrived; carries `llmOutput`
31
+ * (only when `emitDebugEvents: true`) — the UI
32
+ * can render "waiting on LLM" between steps 5-6
33
+ * 7. `processed` — pass complete; carries `bases[]` (new/updated
34
+ * instance URIs)
35
+ *
36
+ * ## Lifecycle (losing peer, or short-circuit)
37
+ *
38
+ * - `batchReady` → `backedOff` — another peer claimed the batch first
39
+ * - `batchReady` → `awaitingAuthor` — no author of the batch is online
40
+ * - `batchReady` → `notCandidate` — this peer stood down for an earlier author
41
+ * - `claimed` → `shapesMissing` — a configured class shape hasn't synced
42
+ * - `claimed` → `emptyTranscript` — the batch drained empty
43
+ * - any → `failed` — the model errored or timed out;
44
+ * `detail` carries why. Distinct from the two above, which are the pass
45
+ * correctly finding nothing to do — reporting "nothing to extract" when
46
+ * the LLM endpoint was unreachable points someone at their transcript
47
+ * instead of at their model settings.
48
+ *
49
+ * ## Lifecycle (one-shot `runInterpretation`)
50
+ *
51
+ * A one-shot pass emits nothing unless the caller passes `observe` (see
52
+ * {@link PerspectiveProxy.runInterpretation}). With it:
53
+ *
54
+ * `runningInterpretation` → [`llmRequestSent` → `llmResponseReceived`] →
55
+ * `processed` | `failed`
56
+ *
57
+ * — plus `claimed` → `finished`/`abandoned` on the neighbourhood stream, so
58
+ * one-shot and watch passes render through the same consumer code. There is
59
+ * no `batchReady`, `gatheringTranscript` or claim: the caller supplied the
60
+ * transcript, and `processorId`/`batchKey` both carry the caller's own
61
+ * `observationId`.
62
+ *
63
+ * ## Payload fields per step
64
+ *
65
+ * All steps carry `perspectiveUuid`, `processorId`, `agentDid`, `itemIds[]`
66
+ * and `batchKey` (the join key to the neighbourhood-state stream).
67
+ * Additional payload:
68
+ *
69
+ * - `backedOff`, `notCandidate` → `detail` = holder / elected-author DID
70
+ * - `shapesMissing` → `detail` = comma-joined missing class URIs
71
+ * - `failed` → `detail` = the error
72
+ * - `llmRequestSent` → `llmInput` = raw prompt
73
+ * - `llmResponseReceived` → `llmOutput` = raw LLM response
74
+ * - `processed` → `bases[]` = new/updated instance URIs
75
+ */
7
76
  export type AutoProcessorStep =
8
77
  | "batchReady"
9
78
  | "claimed"
@@ -12,9 +81,14 @@ export type AutoProcessorStep =
12
81
  | "notCandidate"
13
82
  | "gatheringTranscript"
14
83
  | "runningInterpretation"
84
+ | "llmRequestSent"
85
+ | "llmResponseReceived"
86
+ | "toolCall"
87
+ | "toolResult"
15
88
  | "processed"
16
89
  | "shapesMissing"
17
- | "emptyTranscript";
90
+ | "emptyTranscript"
91
+ | "failed";
18
92
 
19
93
  /** A single step-signal from one auto-processor pass on one perspective. */
20
94
  export interface AutoProcessorEvent {
@@ -26,10 +100,114 @@ export interface AutoProcessorEvent {
26
100
  step: AutoProcessorStep;
27
101
  /** The batch's source item ids (present from `batchReady` onward). */
28
102
  itemIds: string[];
103
+ /**
104
+ * Content hash of the batch — the same value
105
+ * {@link AutoProcessorNeighbourhoodStateEvent.batchKey} carries, and the
106
+ * key that joins the two streams.
107
+ *
108
+ * A UI that renders one row per pass subscribes to both: the
109
+ * perspective-scoped neighbourhood stream opens the row (and names the
110
+ * claimant), while this DID-scoped stream fills in the fine-grained
111
+ * steps and LLM I/O for the pass this agent is running. Matching them on
112
+ * `processorId` alone breaks as soon as a processor runs a second pass;
113
+ * matching on `itemIds` means re-implementing the Rust SHA-256 and its
114
+ * exact serialization. So both streams carry the same key.
115
+ *
116
+ * Present from `batchReady` onward. Optional on the type because a
117
+ * pre-#903 executor does not send it — treat its absence as "cannot
118
+ * correlate", not as an error.
119
+ */
120
+ batchKey?: string;
29
121
  /** Instance base URIs written by the pass (present on `processed`). */
30
122
  bases: string[];
31
123
  /** Free-form context for the step (a holder/elected DID, an error, …). */
32
124
  detail?: string;
125
+ /** Raw LLM prompt this pass fed the model. Present ONLY on
126
+ * `llmRequestSent` events, and only when the processor was configured
127
+ * with `emitDebugEvents: true`. Never carried on `processed`. */
128
+ llmInput?: string;
129
+ /** Raw LLM response this pass received. Present ONLY on
130
+ * `llmResponseReceived` events, and only when the processor was
131
+ * configured with `emitDebugEvents: true`. Never carried on `processed`. */
132
+ llmOutput?: string;
133
+ /**
134
+ * Name of the tool the harness LLM invoked (or that just returned).
135
+ * Present on `toolCall` + `toolResult` events (harness path only).
136
+ */
137
+ toolName?: string;
138
+ /**
139
+ * JSON-encoded arguments the LLM sent to the tool. Present ONLY on
140
+ * `toolCall`; absent on `toolResult` where {@link toolResult} carries
141
+ * the return text instead.
142
+ */
143
+ toolArgsJson?: string;
144
+ /**
145
+ * The tool's return text. Present ONLY on `toolResult`; may be
146
+ * pre-truncated by the emitter with an `…[truncated for event]`
147
+ * marker when the tool returns a large payload (e.g. a `_query`
148
+ * result). Consumers wanting the full text can re-run the tool.
149
+ */
150
+ toolResult?: string;
151
+ }
152
+
153
+ /**
154
+ * Coarse-grained phase of a neighbourhood-state event.
155
+ *
156
+ * `claimed` — this executor just started a pass.
157
+ * `finished` — the pass completed successfully.
158
+ * `abandoned` — the pass short-circuited (missing shape / empty batch /
159
+ * error); the claim will TTL-expire.
160
+ */
161
+ export type NeighbourhoodPhase = "claimed" | "finished" | "abandoned";
162
+
163
+ /**
164
+ * `auto-processor-neighbourhood-state` — perspective-scoped observability
165
+ * event. Fires when THIS executor claims, finishes, or abandons a batch.
166
+ * Anyone with perspective read access sees it, so a UI can render "someone
167
+ * is auto-processing this" without receiving the batch payload or LLM I/O.
168
+ *
169
+ * Cross-executor visibility (peer's claim reaching us via Holochain sync) is
170
+ * NOT covered here; consumers who need that subscribe to `link-added` and
171
+ * filter for the `has_claim` predicate on the shared perspective.
172
+ */
173
+ export interface AutoProcessorNeighbourhoodStateEvent {
174
+ type: "auto-processor-neighbourhood-state";
175
+ perspectiveUuid: string;
176
+ processorId: string;
177
+ /** DID that claimed the batch — the pass owner's DID. */
178
+ claimantDid: string;
179
+ /** SHA-256 hex of the batch's item-id set — merge `claimed` + `finished`
180
+ * for the same key to render a single row in a UI. */
181
+ batchKey: string;
182
+ phase: NeighbourhoodPhase;
183
+ }
184
+
185
+ /**
186
+ * Opt a one-shot `runInterpretation` call into the same event streams a
187
+ * standing watch produces.
188
+ *
189
+ * Without it the call is silent until it resolves — which, on a local model,
190
+ * is minutes of a UI having nothing to say. With it the pass reports
191
+ * `runningInterpretation` → `processed`/`failed` on the DID-scoped stream and
192
+ * `claimed` → `finished`/`abandoned` on the perspective-scoped one.
193
+ */
194
+ export interface RunInterpretationObserveOptions {
195
+ /**
196
+ * The caller's own id for this pass, echoed back as both `processorId` and
197
+ * `batchKey` on every event it emits.
198
+ *
199
+ * Supplied by the caller rather than minted by the executor because
200
+ * `runInterpretation` is a single blocking call: there is no earlier
201
+ * response that could hand back a server-side id, so the events would
202
+ * arrive with nothing to match them against. Any value unique among this
203
+ * client's in-flight passes will do.
204
+ */
205
+ observationId: string;
206
+ /**
207
+ * Also emit `llmRequestSent` / `llmResponseReceived` with the raw prompt
208
+ * and response. Default `false`.
209
+ */
210
+ emitDebugEvents?: boolean;
33
211
  }
34
212
 
35
213
  /** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
@@ -86,6 +264,30 @@ export interface AddAutoProcessorConfig {
86
264
  * runs.
87
265
  */
88
266
  sourceWindowMs?: number;
267
+ /**
268
+ * Optional parent-scope filter for the dedup lookup: when set, only
269
+ * existing instances of the interpretation classes that live under this
270
+ * scope are candidates for upsert. Omit for the whole-perspective dedup
271
+ * set (pre-scope behaviour). Raw form only — see `RawScope`.
272
+ */
273
+ existingScope?: RawScope;
274
+ /**
275
+ * Optional parent-scope target for newly minted instances: when set,
276
+ * every base URI the pass CREATES is additionally linked as a child of
277
+ * `mintScope.id` via the scope's predicate — turning the SoA-tree
278
+ * "children live under this node" pattern from a URI-prefix convention
279
+ * into an actual graph edge. Upserts of pre-existing instances are NOT
280
+ * linked (would multi-parent unrelated graph state). Raw form only —
281
+ * see `RawScope`; the Rust watcher rejects `Model` scopes at runtime.
282
+ */
283
+ mintScope?: RawScope;
284
+ /**
285
+ * Enable full debug observability: persists the raw LLM prompt + response
286
+ * on the pass's `InterpretationRun` (`debugPrompt` / `debugResponse`) AND
287
+ * emits `LlmRequestSent` / `LlmResponseReceived` mid-pass events so a
288
+ * subscribed UI can render "waiting on LLM". Default `false`.
289
+ */
290
+ emitDebugEvents?: boolean;
89
291
  }
90
292
 
91
293
  /**