@coasys/ad4m 0.13.1-staging.1 → 0.13.1-staging.3

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 (243) hide show
  1. package/lib/index.cjs +4199 -1221
  2. package/lib/index.js +4189 -1222
  3. package/lib/src/Ad4mClient.d.ts +7 -0
  4. package/lib/src/Ad4mClient.js +9 -0
  5. package/lib/src/apiClient.d.ts +13 -0
  6. package/lib/src/apiClient.js +67 -12
  7. package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
  8. package/lib/src/generated/api/AuthInfo.d.ts +4 -0
  9. package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
  10. package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
  11. package/lib/src/generated/api/Events.d.ts +13 -3
  12. package/lib/src/generated/api/Events.js +1 -0
  13. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
  14. package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
  15. package/lib/src/generated/api/FlowStateEntry.js +2 -0
  16. package/lib/src/generated/api/IceServer.d.ts +18 -0
  17. package/lib/src/generated/api/IceServer.js +2 -0
  18. package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
  19. package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
  20. package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
  21. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
  22. package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
  23. package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
  24. package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
  25. package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
  26. package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
  27. package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
  28. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
  29. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
  30. package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
  31. package/lib/src/generated/api/PerspectiveResynced.js +2 -0
  32. package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
  33. package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
  34. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
  35. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
  36. package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
  37. package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
  38. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
  39. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
  40. package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
  41. package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
  42. package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
  43. package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
  44. package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
  45. package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
  46. package/lib/src/generated/api/RpcMethods.d.ts +134 -14
  47. package/lib/src/generated/api/RpcMethods.js +12 -0
  48. package/lib/src/generated/api/RuntimeInfo.d.ts +5 -0
  49. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
  50. package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
  51. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
  52. package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
  53. package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
  54. package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
  55. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
  56. package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
  57. package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
  58. package/lib/src/generated/api/SfuCascadePipe.js +2 -0
  59. package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
  60. package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
  61. package/lib/src/generated/api/SfuConfig.d.ts +52 -0
  62. package/lib/src/generated/api/SfuConfig.js +1 -0
  63. package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
  64. package/lib/src/generated/api/SfuDataMessage.js +2 -0
  65. package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
  66. package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
  67. package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
  68. package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
  69. package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
  70. package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
  71. package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
  72. package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
  73. package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
  74. package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
  75. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
  76. package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
  77. package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
  78. package/lib/src/generated/api/SfuRoomInfo.js +1 -0
  79. package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
  80. package/lib/src/generated/api/SfuRoomParams.js +2 -0
  81. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
  82. package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
  83. package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
  84. package/lib/src/generated/api/SfuRoomRoster.js +2 -0
  85. package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
  86. package/lib/src/generated/api/SfuSendDataParams.js +2 -0
  87. package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
  88. package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
  89. package/lib/src/generated/api/SfuStatus.d.ts +24 -0
  90. package/lib/src/generated/api/SfuStatus.js +2 -0
  91. package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
  92. package/lib/src/generated/api/TrackMapEntry.js +2 -0
  93. package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
  94. package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
  95. package/lib/src/generated/api/index.d.ts +3 -0
  96. package/lib/src/index.d.ts +8 -0
  97. package/lib/src/index.js +5 -0
  98. package/lib/src/model/Ad4mModel.d.ts +84 -0
  99. package/lib/src/model/Ad4mModel.js +279 -22
  100. package/lib/src/model/ModelQueryBuilder.d.ts +23 -38
  101. package/lib/src/model/ModelQueryBuilder.js +97 -274
  102. package/lib/src/model/decorators.d.ts +32 -0
  103. package/lib/src/model/decorators.js +40 -1
  104. package/lib/src/model/query-common.js +7 -1
  105. package/lib/src/model/shacl-gen.d.ts +3 -1
  106. package/lib/src/model/shacl-gen.js +13 -1
  107. package/lib/src/model/types.d.ts +52 -2
  108. package/lib/src/model/types.js +8 -0
  109. package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
  110. package/lib/src/neighbourhood/MeshManager.js +1144 -0
  111. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
  112. package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
  113. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
  114. package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
  115. package/lib/src/neighbourhood/Session.d.ts +105 -0
  116. package/lib/src/neighbourhood/Session.js +412 -0
  117. package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
  118. package/lib/src/neighbourhood/SfuManager.js +619 -0
  119. package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
  120. package/lib/src/neighbourhood/SfuTypes.js +8 -0
  121. package/lib/src/perspectives/Container.d.ts +41 -0
  122. package/lib/src/perspectives/Container.js +62 -0
  123. package/lib/src/perspectives/FlowInstance.d.ts +63 -24
  124. package/lib/src/perspectives/FlowInstance.js +74 -31
  125. package/lib/src/perspectives/FlowModels.d.ts +0 -16
  126. package/lib/src/perspectives/FlowModels.js +8 -16
  127. package/lib/src/perspectives/LiveQuery.d.ts +49 -0
  128. package/lib/src/perspectives/LiveQuery.js +169 -0
  129. package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
  130. package/lib/src/perspectives/PerspectiveClient.js +33 -36
  131. package/lib/src/perspectives/PerspectiveProxy.d.ts +71 -168
  132. package/lib/src/perspectives/PerspectiveProxy.js +128 -476
  133. package/lib/src/perspectives/TextContent.d.ts +31 -0
  134. package/lib/src/perspectives/TextContent.js +52 -0
  135. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +111 -6
  136. package/lib/src/perspectives/WakerSubscriptionManager.js +290 -48
  137. package/lib/src/runtime/RuntimeTypes.d.ts +2 -0
  138. package/lib/src/shacl/SHACLFlow.d.ts +7 -4
  139. package/lib/src/shacl/SHACLFlow.js +7 -4
  140. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  141. package/lib/src/shacl/SHACLShape.js +37 -0
  142. package/package.json +2 -2
  143. package/pnpm-workspace.yaml +4 -1
  144. package/src/Ad4mClient.test.ts +90 -18
  145. package/src/Ad4mClient.ts +10 -0
  146. package/src/apiClient.test.ts +128 -2
  147. package/src/apiClient.ts +64 -11
  148. package/src/generated/api/AgentsByDidsRequest.ts +3 -0
  149. package/src/generated/api/AuthInfo.ts +6 -1
  150. package/src/generated/api/CallSessionInfo.ts +20 -0
  151. package/src/generated/api/DiscardBatchRequest.ts +3 -0
  152. package/src/generated/api/Events.ts +14 -3
  153. package/src/generated/api/FlowStateChangedEvent.ts +36 -0
  154. package/src/generated/api/FlowStateEntry.ts +18 -0
  155. package/src/generated/api/IceServer.ts +19 -0
  156. package/src/generated/api/OnlineAgent.ts +6 -1
  157. package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
  158. package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
  159. package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
  160. package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
  161. package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
  162. package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
  163. package/src/generated/api/PerspectiveResynced.ts +7 -0
  164. package/src/generated/api/PerspectiveSubscribed.ts +8 -0
  165. package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
  166. package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
  167. package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
  168. package/src/generated/api/QueryUpdatesLagged.ts +7 -0
  169. package/src/generated/api/RemoveSubjectRequest.ts +7 -0
  170. package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
  171. package/src/generated/api/RpcMethods.ts +68 -8
  172. package/src/generated/api/RuntimeInfo.ts +6 -1
  173. package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
  174. package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
  175. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  176. package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
  177. package/src/generated/api/SfuCascadePipe.ts +3 -0
  178. package/src/generated/api/SfuCascadeStatus.ts +7 -0
  179. package/src/generated/api/SfuConfig.ts +53 -0
  180. package/src/generated/api/SfuDataMessage.ts +23 -0
  181. package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
  182. package/src/generated/api/SfuMigrateEvent.ts +20 -0
  183. package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
  184. package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
  185. package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
  186. package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
  187. package/src/generated/api/SfuRoomInfo.ts +7 -0
  188. package/src/generated/api/SfuRoomParams.ts +3 -0
  189. package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
  190. package/src/generated/api/SfuRoomRoster.ts +12 -0
  191. package/src/generated/api/SfuSendDataParams.ts +7 -0
  192. package/src/generated/api/SfuSetConfigParams.ts +4 -0
  193. package/src/generated/api/SfuStatus.ts +24 -0
  194. package/src/generated/api/TrackMapEntry.ts +18 -0
  195. package/src/generated/api/UpdateSubjectRequest.ts +10 -0
  196. package/src/generated/api/index.ts +3 -0
  197. package/src/index.ts +8 -0
  198. package/src/model/Ad4mModel.test.ts +255 -231
  199. package/src/model/Ad4mModel.ts +322 -23
  200. package/src/model/ModelQueryBuilder.ts +112 -316
  201. package/src/model/abstract-classes.test.ts +225 -0
  202. package/src/model/containment-scope.test.ts +104 -0
  203. package/src/model/decorators.ts +81 -0
  204. package/src/model/query-common.ts +10 -1
  205. package/src/model/shacl-gen.ts +13 -0
  206. package/src/model/types.ts +63 -2
  207. package/src/neighbourhood/MeshManager.test.ts +2640 -0
  208. package/src/neighbourhood/MeshManager.ts +1350 -0
  209. package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
  210. package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
  211. package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
  212. package/src/neighbourhood/Session.test.ts +800 -0
  213. package/src/neighbourhood/Session.ts +525 -0
  214. package/src/neighbourhood/SfuManager.test.ts +677 -0
  215. package/src/neighbourhood/SfuManager.ts +803 -0
  216. package/src/neighbourhood/SfuTypes.ts +40 -0
  217. package/src/perspectives/Container.test.ts +65 -0
  218. package/src/perspectives/Container.ts +46 -0
  219. package/src/perspectives/FlowInstance.ts +108 -31
  220. package/src/perspectives/FlowModels.ts +8 -18
  221. package/src/perspectives/LiveQuery.test.ts +197 -0
  222. package/src/perspectives/LiveQuery.ts +189 -0
  223. package/src/perspectives/PerspectiveClient.ts +51 -51
  224. package/src/perspectives/PerspectiveProxy.test.ts +93 -398
  225. package/src/perspectives/PerspectiveProxy.ts +133 -537
  226. package/src/perspectives/TextContent.test.ts +123 -0
  227. package/src/perspectives/TextContent.ts +36 -0
  228. package/src/perspectives/WakerSubscriptionManager.test.ts +421 -21
  229. package/src/perspectives/WakerSubscriptionManager.ts +349 -62
  230. package/src/runtime/RuntimeTypes.ts +2 -0
  231. package/src/shacl/SHACLFlow.ts +7 -4
  232. package/src/shacl/SHACLShape.test.ts +2 -1
  233. package/src/shacl/SHACLShape.ts +49 -0
  234. package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
  235. package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
  236. package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
  237. package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
  238. package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
  239. package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
  240. /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
  241. /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
  242. /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
  243. /package/lib/src/generated/api/{PerspectiveSubscribeQueryResult.js → FlowStateChangedEvent.js} +0 -0
@@ -12,16 +12,150 @@ export interface WakerSubscription {
12
12
  type: "mention" | "channel-messages";
13
13
  perspective: string;
14
14
  channel: string;
15
+ /** SPARQL, or with `className` a model query (JSON) over that class. */
15
16
  query: string;
17
+ /**
18
+ * The class `query` reads, as a model query. A mention subscription has
19
+ * one, from the executor's `get_mention_waker_config`: the built-in
20
+ * `ad4m://TextContent`; a children subscription has the built-in
21
+ * `ad4m://Container`, from `generate_waker_query` (#1446). Without it
22
+ * `query` is SPARQL.
23
+ */
24
+ className?: string;
25
+ /**
26
+ * A mention subscription's terms (profile names and the DID), from
27
+ * `get_mention_waker_config`. The query matches substrings, so a record
28
+ * wakes only when its text holds one of these as a whole word
29
+ * ({@link holdsAWholeWordTerm}); without them a mention subscription is
30
+ * refused.
31
+ */
32
+ terms?: string[];
16
33
  neighbourhood?: string;
17
34
  }
18
35
 
36
+ /** A letter, combining mark, digit or underscore: what a term must not touch. */
37
+ const WORD_CHAR = "[\\p{L}\\p{M}\\p{N}_]";
38
+
39
+ /**
40
+ * The elements a message's HTML is made of. A `<` before any other name is text:
41
+ * We stores plain text, where "<hey Data> can you look" is words.
42
+ */
43
+ const ELEMENT =
44
+ "a|abbr|b|bdi|bdo|blockquote|br|caption|center|cite|code|col|colgroup|dd|del|details|dfn|div|dl|dt|em|" +
45
+ "figcaption|figure|font|h[1-6]|hr|i|img|ins|kbd|label|li|mark|ol|p|pre|q|s|samp|section|article|small|" +
46
+ "span|strike|strong|sub|summary|sup|table|tbody|td|tfoot|th|thead|time|tr|u|ul|var|wbr|script|style";
47
+ /** An attribute: a name, then optionally `=` and a quoted value (which may hold `>`) or an unquoted one. */
48
+ const ATTRIBUTE = `\\s+[A-Za-z_:][-\\w:.]*(?:\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s"'=<>\`]+))?`;
49
+ /**
50
+ * Markup: a comment, a `<script>`/`<style>` element with its contents, or a tag of
51
+ * a known element whose rest is a valid attribute list. "a < b" and
52
+ * "if a <b then ask Data, else c -> d" are text: the comma is no attribute.
53
+ */
54
+ const TAG = new RegExp(
55
+ `<!--[\\s\\S]*?-->` +
56
+ `|<(script|style)(?=[\\s/>])(?:${ATTRIBUTE})*\\s*>[\\s\\S]*?<\\/\\1\\s*>` +
57
+ `|<(?:${ELEMENT})(?=[\\s/>])(?:${ATTRIBUTE})*\\s*\\/?>` +
58
+ `|<\\/(?:${ELEMENT})\\s*>`,
59
+ "gi",
60
+ );
61
+ /** Tags that break a line: replaced by a space, so `<p>hi</p><p>Data</p>` keeps "Data" a word. */
62
+ const BREAKING_TAG = /^<\/?(?:p|div|br|hr|li|ul|ol|h[1-6]|blockquote|pre|tr|td|th|table|section|article)\b/i;
63
+ /**
64
+ * The attributes a mention puts its target's DID in: Flux's `<a data-type="mention"
65
+ * href="did:…">`, older Flux messages' `<span data-id="did:…">`, and We's editor chip
66
+ * `<span class="we-mention" data-did="did:…">`.
67
+ */
68
+ const ATTRIBUTES = new RegExp(ATTRIBUTE, "g");
69
+ const MENTION_TARGET = /^\s+(?:href|data-id|data-did)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))$/i;
70
+
71
+ /**
72
+ * How much of a record's text the word check reads. Dropping markup costs time
73
+ * quadratic in a run of unclosed `<script>`, `<style>` or `<!--` openers, so a
74
+ * very long text could hold the event loop for seconds, and a row that holds
75
+ * no term is checked again on every result while it is in the window. A term
76
+ * past this many characters does not wake.
77
+ */
78
+ export const MENTION_TEXT_LIMIT = 16_384;
79
+
80
+ const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
81
+
82
+ function decodeEntities(s: string): string {
83
+ return s.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, ref: string) => {
84
+ if (ref[0] !== "#") return ENTITIES[ref.toLowerCase()] ?? whole;
85
+ const code = ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
86
+ return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
87
+ });
88
+ }
89
+
90
+ /**
91
+ * What a reader sees of `text`, and the DIDs its mentions point at. `text` may be
92
+ * HTML (TextContent allows it): tag names and attributes are markup, not words, so
93
+ * a bot named "Data" must not wake on `data-type="mention"` in a mention of
94
+ * someone else. Plain text passes through unchanged, apart from entities.
95
+ */
96
+ function readableParts(text: string): { visible: string; targets: string[] } {
97
+ const targets: string[] = [];
98
+ const visible = text.replace(TAG, (tag, scriptOrStyle?: string) => {
99
+ if (scriptOrStyle) return " ";
100
+ if (tag.startsWith("<!--")) return "";
101
+ // Parse complete attributes first: a DID-shaped string inside `title`
102
+ // is not a target attribute and must not wake an agent.
103
+ for (const attribute of tag.matchAll(ATTRIBUTES)) {
104
+ const target = MENTION_TARGET.exec(attribute[0]);
105
+ if (target) targets.push(decodeEntities(target[1] ?? target[2] ?? target[3]));
106
+ }
107
+ return BREAKING_TAG.test(tag) ? " " : "";
108
+ });
109
+ return { visible: decodeEntities(visible), targets };
110
+ }
111
+
112
+ /**
113
+ * Whether `text` holds one of `terms` as a whole word, case-insensitively:
114
+ * "Data" is in "hi Data!", "@data" and "Data's turn", not in "metadata" or
115
+ * "database". A term is matched literally (regex characters, quotes) and must
116
+ * not touch a letter, mark, digit or underscore on either side, so a name
117
+ * that starts or ends with punctuation still matches. Same rule as #1459's
118
+ * SPARQL `(?:^|\W)term(?:\W|$)`.
119
+ *
120
+ * The rule runs on the visible text only: in HTML, tags and attributes are
121
+ * dropped and entities decoded first. A mention's target attribute
122
+ * (`href`, `data-id`, `data-did`) matches an exact, case-sensitive DID term, which
123
+ * is how a mention by DID is found when the DID is not in the visible text.
124
+ *
125
+ * The mention query's `contains` matches substrings (model query has no word
126
+ * match); this is the check that keeps "data" from waking on "metadata".
127
+ * It reads the first {@link MENTION_TEXT_LIMIT} characters only.
128
+ */
129
+ export function holdsAWholeWordTerm(text: string, terms: string[]): boolean {
130
+ const { visible, targets } = readableParts(text.slice(0, MENTION_TEXT_LIMIT));
131
+ return terms.some((term) => {
132
+ if (!term) return false;
133
+ if (term.startsWith("did:") && targets.includes(term)) return true;
134
+ const escaped = term.replace(/[\\^$.*+?()[\]{}|\/]/g, "\\$&");
135
+ return new RegExp(`(?<!${WORD_CHAR})${escaped}(?!${WORD_CHAR})`, "iu").test(visible);
136
+ });
137
+ }
138
+
139
+ /** The built-in `Container` (`Container.builtinUri`; not imported, so the
140
+ * plugin bundle does not pull in the model layer). */
141
+ const CONTAINER = "ad4m://Container";
142
+
19
143
  /** Per-message parent resolution result for mention subscriptions. */
20
144
  export interface MentionMessage {
21
- /** The message's expression address (source of the body link). */
145
+ /** The mentioned record's id. */
22
146
  address: string;
23
- /** All parent addresses this message belongs to (channels, conversations, etc.). */
147
+ /**
148
+ * Every container holding it (channels, threads, calls, blocks): whatever
149
+ * links it with `ad4m://has_child`, and every instance of a class whose
150
+ * `children` relation links it. A record can sit in several.
151
+ */
24
152
  parents: string[];
153
+ /**
154
+ * Everything above the parents, nearest first: their parents, theirs, and so on up to the
155
+ * manager's `ancestorDepth`. Each address once, however many paths reach it. Empty when the
156
+ * parents have none, or the walk could not be made.
157
+ */
158
+ ancestors: string[];
25
159
  }
26
160
 
27
161
  export interface WakerLogger {
@@ -38,9 +172,23 @@ export interface WakerSubscriptionManagerOptions {
38
172
  logger: WakerLogger;
39
173
  /** Debounce interval in ms before firing the wake callback (default 2000) */
40
174
  debounceMs?: number;
41
- /** Called when a subscription fires (after debounce). Return value is ignored.
42
- * For mention subs, `mentions` contains per-message parent info. */
43
- onWake: (sub: WakerSubscription, result: any, mentions?: MentionMessage[]) => void;
175
+ /**
176
+ * How many levels above a mentioned item's parents to report as `ancestors` (default 3).
177
+ * Each level is one batched query, so the walk is bounded by this depth and by
178
+ * what the levels hold. 0 reports parents only.
179
+ */
180
+ ancestorDepth?: number;
181
+ /**
182
+ * Called when a subscription fires (after debounce). For mention subs, `mentions` holds every
183
+ * mention not yet delivered, with its parent info. Resolve `false` (or reject) when the wake did
184
+ * not reach the agent: those mentions stay out of the persisted seen set and are offered again
185
+ * after `retryWakeMs`, so a wake lost to a restarting gateway is not lost for good.
186
+ */
187
+ onWake: (
188
+ sub: WakerSubscription,
189
+ result: any,
190
+ mentions?: MentionMessage[],
191
+ ) => void | boolean | Promise<void | boolean>;
44
192
  /** Called when the active subscription list changes (for persistence). */
45
193
  onPersist?: (subscriptions: WakerSubscription[], seenMessages: Record<string, string[]>) => void;
46
194
  /** Previously persisted seen message IDs per subscription. Seeds seenMessages on resubscribe to avoid duplicate wakes. */
@@ -59,6 +207,9 @@ export interface WakerSubscriptionManagerOptions {
59
207
  * so the re-attempt cycle never saw it (#1016).
60
208
  */
61
209
  subscribeTimeoutMs?: number;
210
+ /** First delay before offering an undelivered mention wake again (default 5000); doubles per
211
+ * failed attempt, up to 60000. */
212
+ retryWakeMs?: number;
62
213
  }
63
214
 
64
215
  /**
@@ -108,12 +259,14 @@ export class WakerSubscriptionManager {
108
259
  private perspectiveClient: any;
109
260
  private logger: WakerLogger;
110
261
  private debounceMs: number;
111
- private onWake: (sub: WakerSubscription, result: any, mentions?: MentionMessage[]) => void;
262
+ private ancestorDepth: number;
263
+ private onWake: WakerSubscriptionManagerOptions["onWake"];
112
264
  private onPersist?: (subscriptions: WakerSubscription[], seenMessages: Record<string, string[]>) => void;
113
265
  private QuerySubscriptionProxyCtor: any;
114
266
  private previousSeenMessages: Record<string, string[]>;
115
267
  private retryPendingMs: number;
116
268
  private subscribeTimeoutMs: number;
269
+ private retryWakeMs: number;
117
270
 
118
271
  private proxies = new Map<string, any>();
119
272
  private activeSubscriptions = new Map<string, WakerSubscription>();
@@ -136,17 +289,33 @@ export class WakerSubscriptionManager {
136
289
  /** Per-subscription set of already-processed message addresses (for mention subs)
137
290
  * or serialized result hash (for channel-messages subs). */
138
291
  private seenMessages = new Map<string, Set<string>>();
292
+ /**
293
+ * Per mention subscription: the addresses whose wake was delivered, or that were history when
294
+ * the subscription opened. This, not `seenMessages`, is what gets persisted: an address joins
295
+ * `seenMessages` as soon as it is read, while its parents are still resolving and before any
296
+ * wake, so a restart in between must not take it as done.
297
+ */
298
+ private delivered = new Map<string, Set<string>>();
299
+ /**
300
+ * Per mention subscription: mentions read but whose wake has not been delivered yet, keyed by
301
+ * address. They accumulate across a debounce window, so one wake names all of them.
302
+ */
303
+ private undelivered = new Map<string, Map<string, MentionMessage>>();
304
+ /** Failed wake attempts in a row per subscription, for the retry backoff. */
305
+ private wakeFailures = new Map<string, number>();
139
306
 
140
307
  constructor(options: WakerSubscriptionManagerOptions) {
141
308
  this.perspectiveClient = options.perspectiveClient;
142
309
  this.logger = options.logger;
143
310
  this.debounceMs = options.debounceMs ?? 2000;
311
+ this.ancestorDepth = options.ancestorDepth ?? 3;
144
312
  this.onWake = options.onWake;
145
313
  this.onPersist = options.onPersist;
146
314
  this.QuerySubscriptionProxyCtor = options.QuerySubscriptionProxy ?? null;
147
315
  this.previousSeenMessages = options.previousSeenMessages ?? {};
148
316
  this.retryPendingMs = options.retryPendingMs ?? 30000;
149
317
  this.subscribeTimeoutMs = options.subscribeTimeoutMs ?? 15000;
318
+ this.retryWakeMs = options.retryWakeMs ?? 5000;
150
319
  }
151
320
 
152
321
  /** A token identifying this attempt at subscribing `id`. */
@@ -162,7 +331,7 @@ export class WakerSubscriptionManager {
162
331
  }
163
332
 
164
333
  /**
165
- * Create a live SPARQL subscription.
334
+ * Create a live subscription: SPARQL, or a model query when `sub.className` is set.
166
335
  * If a subscription with the same id already exists, it is disposed first.
167
336
  */
168
337
  async subscribe(sub: WakerSubscription): Promise<void> {
@@ -174,18 +343,22 @@ export class WakerSubscriptionManager {
174
343
  throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
175
344
  }
176
345
  const QuerySubscriptionProxy = this.QuerySubscriptionProxyCtor;
346
+ if (sub.type === "mention" && sub.className && !sub.terms?.length) {
347
+ // Without terms the whole-word check cannot run, and every substring
348
+ // ("metadata" for "data") would wake the agent.
349
+ throw new Error(
350
+ `Waker subscription ${sub.id}: a mention subscription needs its terms (get_mention_waker_config returns them)`,
351
+ );
352
+ }
177
353
 
178
354
  this.logger.info(
179
355
  `[waker] ${sub.id}: creating subscription (perspective=${sub.perspective}, type=${sub.type})`,
180
356
  );
181
- this.logger.info(`[waker] ${sub.id}: SPARQL query:\n${sub.query}`);
357
+ this.logger.info(`[waker] ${sub.id}: ${sub.className ? `model query over ${sub.className}` : "SPARQL query"}:\n${sub.query}`);
182
358
 
183
- const proxy = new QuerySubscriptionProxy(
184
- sub.perspective,
185
- sub.query,
186
- this.perspectiveClient,
187
- );
188
- proxy.isSPARQL = true;
359
+ const proxy = sub.className
360
+ ? new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient, sub.className)
361
+ : new QuerySubscriptionProxy(sub.perspective, sub.query, this.perspectiveClient);
189
362
  // Suppress unhandled rejection from proxy.initialized — QuerySubscriptionProxy
190
363
  // rejects this promise internally when subscribe() fails, and if nobody catches
191
364
  // it before the next microtask it crashes the process.
@@ -225,6 +398,7 @@ export class WakerSubscriptionManager {
225
398
  // reported as active or persisted as if it were.
226
399
  this.activeSubscriptions.delete(sub.id);
227
400
  this.seenMessages.delete(sub.id);
401
+ this.delivered.delete(sub.id);
228
402
  this.persist();
229
403
  // Keep it pending and re-attempt: the usual cause (locked wallet, executor
230
404
  // mid-restart, a handshake the executor never answered) clears on its
@@ -249,94 +423,104 @@ export class WakerSubscriptionManager {
249
423
  this.logger.info(`[waker] ${sub.id}: subscription initialized successfully`);
250
424
 
251
425
  // Seed from persisted seen messages so we don't re-wake after restart
426
+ const restored = Object.prototype.hasOwnProperty.call(this.previousSeenMessages, sub.id);
252
427
  const seen = new Set<string>(this.previousSeenMessages[sub.id] ?? []);
253
428
  this.seenMessages.set(sub.id, seen);
429
+ this.delivered.set(sub.id, new Set(seen));
254
430
  if (seen.size > 0) {
255
431
  this.logger.info(`[waker] ${sub.id}: seeded ${seen.size} seen message(s) from persisted state`);
256
432
  }
257
433
 
258
- proxy.onResult(async (result: any) => {
434
+ // `opening` is the result the subscription holds when it opens (`proxy.result`): `onResult`
435
+ // only reports later changes, so this is the one chance to see what was written meanwhile.
436
+ const handleResult = async (result: any, opening = false) => {
259
437
  this.logger.info(
260
- `[waker] ${sub.id}: onResult fired — type=${typeof result}, isArray=${Array.isArray(result)}, value=${String(JSON.stringify(result)).substring(0, 500)}`,
438
+ `[waker] ${sub.id}: ${opening ? "opening result" : "onResult fired"} — type=${typeof result}, isArray=${Array.isArray(result)}, value=${String(JSON.stringify(result)).substring(0, 500)}`,
261
439
  );
262
440
 
263
- // Query engine can deliver non-array values (e.g. false) on disconnect/reconnect — ignore them
264
- if (!Array.isArray(result)) {
441
+ // A model subscription delivers `{ instances }`, SPARQL an array of
442
+ // rows. Anything else (e.g. `false` on a disconnect/reconnect) is
443
+ // ignored.
444
+ const rows: unknown = sub.className ? result?.instances : result;
445
+ if (!Array.isArray(rows)) {
265
446
  this.logger.warn(
266
- `[waker] ${sub.id}: ignoring non-array result: ${JSON.stringify(result)}`,
447
+ `[waker] ${sub.id}: ignoring result without ${sub.className ? "instances" : "rows"}: ${JSON.stringify(result)}`,
267
448
  );
268
449
  return;
269
450
  }
270
451
 
271
452
  if (sub.type === "mention") {
272
- // For mention subscriptions: track seen message addresses.
273
- // Only wake for messages we haven't seen before.
453
+ // For mention subscriptions: track seen record ids.
454
+ // Only wake for records we haven't seen before.
274
455
  const currentSeen = this.seenMessages.get(sub.id) ?? new Set<string>();
275
456
  const newMessages: string[] = [];
276
457
 
277
- for (const item of result) {
278
- if (item && item.source && !currentSeen.has(item.source)) {
279
- newMessages.push(item.source);
458
+ const terms = sub.terms ?? [];
459
+ for (const item of rows as any[]) {
460
+ // A SPARQL row names the record as `source`, a model row as `id`.
461
+ const address = sub.className ? item?.id : item?.source;
462
+ if (typeof address !== "string" || !address || currentSeen.has(address)) continue;
463
+ if (terms.length) {
464
+ // The mention query matched a substring; wake only on a whole word.
465
+ const text = Array.isArray(item.text) ? item.text.join(" ") : item.text;
466
+ if (typeof text !== "string" || !holdsAWholeWordTerm(text, terms)) {
467
+ this.logger.debug(`[waker] ${sub.id}: ${address} holds no term as a whole word, skipping`);
468
+ continue;
469
+ }
280
470
  }
471
+ currentSeen.add(address);
472
+ newMessages.push(address);
281
473
  }
282
474
 
283
475
  if (newMessages.length === 0) {
284
476
  this.logger.info(
285
- `[waker] ${sub.id}: all ${result.length} items already seen, skipping`,
477
+ `[waker] ${sub.id}: no new mention among ${rows.length} items, skipping`,
478
+ );
479
+ return;
480
+ }
481
+
482
+ if (opening && !restored) {
483
+ // A new subscription: what it opens on is history, readable on demand, not news.
484
+ this.seenMessages.set(sub.id, currentSeen);
485
+ const done = this.delivered.get(sub.id) ?? new Set<string>();
486
+ for (const address of newMessages) done.add(address);
487
+ this.delivered.set(sub.id, done);
488
+ this.logger.info(
489
+ `[waker] ${sub.id}: ${newMessages.length} existing mention(s) taken as history, not woken`,
286
490
  );
287
491
  return;
288
492
  }
289
493
 
290
494
  this.logger.info(
291
- `[waker] ${sub.id}: ${newMessages.length} new message(s) out of ${result.length} total`,
495
+ `[waker] ${sub.id}: ${newMessages.length} new message(s) out of ${rows.length} total`,
292
496
  );
293
497
 
294
- // Resolve parents per new message
498
+ // Resolve parents, and the chain above them, per new message
295
499
  const mentions: MentionMessage[] = [];
296
500
  for (const msgAddr of newMessages) {
297
- const parents: string[] = [];
298
- try {
299
- const parentQuery = `SELECT ?source WHERE { ?source <ad4m://has_child> <${msgAddr}> . }`;
300
- this.logger.info(`[waker] ${sub.id}: resolving parents for ${msgAddr}`);
301
- const rows: unknown = await this.perspectiveClient.querySparql(sub.perspective, parentQuery);
302
- if (Array.isArray(rows)) {
303
- // A row omits a variable left unbound in its solution.
304
- parents.push(...rows.map((row) => row?.source).filter((source): source is string => typeof source === "string"));
305
- }
306
- } catch (err: any) {
307
- this.logger.warn(
308
- `[waker] ${sub.id}: parent resolution failed for ${msgAddr} — ${err?.message ?? err}`,
309
- );
310
- }
501
+ this.logger.info(`[waker] ${sub.id}: resolving parents for ${msgAddr}`);
502
+ const parents = await this.parentsOf(sub, [msgAddr]);
503
+ const ancestors = await this.ancestorsOf(sub, msgAddr, parents);
311
504
  this.logger.info(
312
- `[waker] ${sub.id}: message ${msgAddr} has ${parents.length} parent(s): ${parents.join(", ")}`,
505
+ `[waker] ${sub.id}: message ${msgAddr} has ${parents.length} parent(s): ${parents.join(", ")}` +
506
+ (ancestors.length ? `; ancestors: ${ancestors.join(", ")}` : ""),
313
507
  );
314
- mentions.push({ address: msgAddr, parents });
508
+ mentions.push({ address: msgAddr, parents, ancestors });
315
509
  }
316
510
 
317
- // Mark all new messages as seen
318
- for (const addr of newMessages) {
319
- currentSeen.add(addr);
320
- }
321
511
  this.seenMessages.set(sub.id, currentSeen);
512
+ const pending = this.undelivered.get(sub.id) ?? new Map<string, MentionMessage>();
513
+ for (const mention of mentions) pending.set(mention.address, mention);
514
+ this.undelivered.set(sub.id, pending);
322
515
 
323
- // Debounce the wake callback
324
- const existing = this.debounceTimers.get(sub.id);
325
- if (existing) clearTimeout(existing);
326
-
327
- this.debounceTimers.set(
328
- sub.id,
329
- setTimeout(() => {
330
- this.onWake(sub, result, mentions);
331
- this.debounceTimers.delete(sub.id);
332
- this.persist();
333
- }, this.debounceMs),
334
- );
516
+ this.scheduleMentionWake(sub, result, this.debounceMs);
335
517
  } else {
518
+ // A container's contents when the subscription opens are not an update.
519
+ if (opening) return;
336
520
  // For channel-messages: always notify the agent on every subscription push.
337
521
  // No deduplication — the agent reads recent messages itself.
338
522
  this.logger.info(
339
- `[waker] ${sub.id}: channel update (${result.length} items)`,
523
+ `[waker] ${sub.id}: channel update (${rows.length} items)`,
340
524
  );
341
525
 
342
526
  const existing = this.debounceTimers.get(sub.id);
@@ -350,7 +534,8 @@ export class WakerSubscriptionManager {
350
534
  }, this.debounceMs),
351
535
  );
352
536
  }
353
- });
537
+ };
538
+ proxy.onResult((result: any) => handleResult(result));
354
539
 
355
540
  if (this.isStale(sub.id, token)) {
356
541
  try { proxy.dispose(); } catch {}
@@ -358,6 +543,15 @@ export class WakerSubscriptionManager {
358
543
  }
359
544
  this.proxies.set(sub.id, proxy);
360
545
  this.activeSubscriptions.set(sub.id, sub);
546
+ // After a restart this wakes on mentions written while the waker was down; on a new
547
+ // subscription it records the existing ones as history.
548
+ if (proxy.result !== undefined) {
549
+ try {
550
+ await handleResult(proxy.result, true);
551
+ } catch (e: any) {
552
+ this.logger.warn(`[waker] ${sub.id}: reading the opening result failed: ${e?.message ?? e}`);
553
+ }
554
+ }
361
555
  this.persist();
362
556
 
363
557
  this.logger.info(
@@ -436,9 +630,63 @@ export class WakerSubscriptionManager {
436
630
  this.activeSubscriptions.delete(id);
437
631
  this.pendingSubscriptions.delete(id);
438
632
  this.seenMessages.delete(id);
633
+ this.delivered.delete(id);
634
+ this.undelivered.delete(id);
635
+ this.wakeFailures.delete(id);
439
636
  if (persist) this.persist();
440
637
  }
441
638
 
639
+ /** (Re)start the timer that offers `sub`'s undelivered mentions to `onWake` after `delayMs`. */
640
+ private scheduleMentionWake(sub: WakerSubscription, result: any, delayMs: number): void {
641
+ const existing = this.debounceTimers.get(sub.id);
642
+ if (existing) clearTimeout(existing);
643
+ this.debounceTimers.set(
644
+ sub.id,
645
+ setTimeout(() => {
646
+ this.debounceTimers.delete(sub.id);
647
+ void this.deliverMentions(sub, result);
648
+ }, delayMs),
649
+ );
650
+ }
651
+
652
+ /**
653
+ * Offer every undelivered mention of `sub` in one wake. On delivery they join the persisted
654
+ * seen set; on failure they stay undelivered and are offered again with backoff.
655
+ */
656
+ private async deliverMentions(sub: WakerSubscription, result: any): Promise<void> {
657
+ const pending = this.undelivered.get(sub.id);
658
+ if (!pending?.size || !this.activeSubscriptions.has(sub.id)) return;
659
+ const mentions = Array.from(pending.values());
660
+ let delivered: boolean;
661
+ try {
662
+ delivered = (await this.onWake(sub, result, mentions)) !== false;
663
+ } catch (e: any) {
664
+ this.logger.warn(`[waker] ${sub.id}: wake callback threw: ${e?.message ?? e}`);
665
+ delivered = false;
666
+ }
667
+ // Disposed while the wake was in flight: nothing left to retry or persist.
668
+ if (this.undelivered.get(sub.id) !== pending) return;
669
+ if (!delivered) {
670
+ const failures = (this.wakeFailures.get(sub.id) ?? 0) + 1;
671
+ this.wakeFailures.set(sub.id, failures);
672
+ const delay = Math.min(this.retryWakeMs * 2 ** (failures - 1), 60_000);
673
+ this.logger.warn(
674
+ `[waker] ${sub.id}: wake for ${mentions.length} mention(s) not delivered, offering again in ${delay}ms`,
675
+ );
676
+ // A newer result arriving meanwhile restarts the timer and joins this wake.
677
+ if (!this.debounceTimers.has(sub.id)) this.scheduleMentionWake(sub, result, delay);
678
+ return;
679
+ }
680
+ this.wakeFailures.delete(sub.id);
681
+ const done = this.delivered.get(sub.id) ?? new Set<string>();
682
+ for (const mention of mentions) {
683
+ pending.delete(mention.address);
684
+ done.add(mention.address);
685
+ }
686
+ this.delivered.set(sub.id, done);
687
+ this.persist();
688
+ }
689
+
442
690
  /** Dispose all active subscriptions and drop anything still pending. */
443
691
  disposeAll(): void {
444
692
  // Bump the epoch first: in-flight subscribe() calls have no proxy in the
@@ -464,10 +712,49 @@ export class WakerSubscriptionManager {
464
712
  return this.activeSubscriptions.has(id);
465
713
  }
466
714
 
715
+ /**
716
+ * Everything holding any of `addresses`, in one model query: a `Container`
717
+ * step in (#1446). The executor follows `ad4m://has_child` on any node and
718
+ * each class's own `children` relation on its instances, so the waker
719
+ * looks up no predicate. Failures count as none.
720
+ */
721
+ private async parentsOf(sub: WakerSubscription, addresses: string[]): Promise<string[]> {
722
+ if (!addresses.length) return [];
723
+ return this.containers(sub, { ids: [...new Set(addresses)], direction: "in" }, addresses);
724
+ }
725
+
726
+ /**
727
+ * The chain above an item's parents, nearest first, up to `ancestorDepth` levels: one
728
+ * transitive `Container` walk in from the parents, bounded by `maxDepth`. The executor walks
729
+ * containment as a graph, so each address comes once however many paths reach it, and a
730
+ * cycle ends. The item and its parents are never reported as ancestors.
731
+ */
732
+ private async ancestorsOf(sub: WakerSubscription, address: string, parents: string[]): Promise<string[]> {
733
+ if (!parents.length || this.ancestorDepth <= 0) return [];
734
+ const scope = { ids: parents, direction: "in", transitive: true, maxDepth: this.ancestorDepth };
735
+ const seen = new Set<string>([address, ...parents]);
736
+ return (await this.containers(sub, scope, parents)).filter((id) => !seen.has(id));
737
+ }
738
+
739
+ /** The ids of the `Container` rows `parent` scopes to, in the executor's order. */
740
+ private async containers(sub: WakerSubscription, parent: Record<string, unknown>, from: string[]): Promise<string[]> {
741
+ try {
742
+ const query = JSON.stringify({ parent, properties: [] });
743
+ const result = await this.perspectiveClient.modelQuery(sub.perspective, CONTAINER, query);
744
+ const instances: unknown = result?.instances;
745
+ if (!Array.isArray(instances)) return [];
746
+ return instances.map((row) => row?.id).filter((id): id is string => typeof id === "string");
747
+ } catch (err: any) {
748
+ this.logger.warn(`[waker] ${sub.id}: containment lookup failed for ${JSON.stringify(from)} — ${err?.message ?? err}`);
749
+ return [];
750
+ }
751
+ }
752
+
467
753
  private persist(): void {
468
754
  if (this.onPersist) {
469
755
  const seen: Record<string, string[]> = {};
470
- for (const [id, set] of this.seenMessages) {
756
+ // Only what was delivered: anything else must wake again after a restart.
757
+ for (const [id, set] of this.delivered) {
471
758
  seen[id] = Array.from(set);
472
759
  }
473
760
  this.onPersist(this.getActive(), seen);
@@ -8,6 +8,8 @@ export class SentMessage {
8
8
 
9
9
  export class RuntimeInfo {
10
10
  ad4mExecutorVersion: string;
11
+ /** The commit the executor was built from, or null when the build could not tell. */
12
+ ad4mExecutorCommit: string | null;
11
13
  isInitialized: Boolean;
12
14
  isUnlocked: Boolean;
13
15
  }
@@ -317,10 +317,13 @@ export interface FlowTransition {
317
317
  * - What states exist and their per-state guards (via `requires`)
318
318
  * - How to transition between states (via transitions + consensus rules)
319
319
  *
320
- * State lives on the on-graph `FlowInstanceRecord.currentState` and is
321
- * read/written through the `FlowInstance` wrapper class
322
- * ({@link FlowInstance.start} / {@link FlowInstance.findAll}) — see design
323
- * doc §4.3/§5.
320
+ * A running instance's state is not stored on the graph: the executor
321
+ * derives it from the signed transition proposals and keeps what it derived
322
+ * per agent, outside the perspective (#1424). Read it through the
323
+ * `FlowInstance` wrapper ({@link FlowInstance.start} /
324
+ * {@link FlowInstance.findAll}, `currentStateName`) or
325
+ * `PerspectiveProxy.flowStates`, and follow it with
326
+ * `PerspectiveProxy.onFlowStateChanged` — see design doc §4.3/§5.
324
327
  *
325
328
  * @example
326
329
  * ```typescript
@@ -5,7 +5,8 @@ import { join } from 'path';
5
5
  import { Parser } from 'n3';
6
6
 
7
7
  // Links the executor's parse_shacl_to_links writes for a shape that uses every
8
- // field (golden[0]) and one with empty action lists (golden[1]); its test
8
+ // field (golden[0]), one with empty action lists (golden[1]) and an abstract
9
+ // class (golden[2], #1435); its test
9
10
  // `parse_shacl_to_links_matches_the_golden_fixture` pins the same file.
10
11
  const goldenCases = JSON.parse(readFileSync(
11
12
  join(__dirname, '../../../rust-executor/src/perspectives/fixtures/shacl_writer_golden.json'), 'utf8'));