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

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 (222) hide show
  1. package/lib/index.cjs +3789 -1192
  2. package/lib/index.js +3783 -1193
  3. package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
  4. package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
  5. package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
  6. package/lib/src/generated/api/Events.d.ts +13 -3
  7. package/lib/src/generated/api/Events.js +1 -0
  8. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
  9. package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
  10. package/lib/src/generated/api/FlowStateEntry.js +2 -0
  11. package/lib/src/generated/api/IceServer.d.ts +18 -0
  12. package/lib/src/generated/api/IceServer.js +2 -0
  13. package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
  14. package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
  15. package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
  16. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
  17. package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
  18. package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
  19. package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
  20. package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
  21. package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
  22. package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
  23. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
  24. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
  25. package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
  26. package/lib/src/generated/api/PerspectiveResynced.js +2 -0
  27. package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
  28. package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
  29. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
  30. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
  31. package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
  32. package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
  33. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
  34. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
  35. package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
  36. package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
  37. package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
  38. package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
  39. package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
  40. package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
  41. package/lib/src/generated/api/RpcMethods.d.ts +134 -14
  42. package/lib/src/generated/api/RpcMethods.js +12 -0
  43. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
  44. package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
  45. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
  46. package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
  47. package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
  48. package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
  49. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
  50. package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
  51. package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
  52. package/lib/src/generated/api/SfuCascadePipe.js +2 -0
  53. package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
  54. package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
  55. package/lib/src/generated/api/SfuConfig.d.ts +52 -0
  56. package/lib/src/generated/api/SfuConfig.js +1 -0
  57. package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
  58. package/lib/src/generated/api/SfuDataMessage.js +2 -0
  59. package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
  60. package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
  61. package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
  62. package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
  63. package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
  64. package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
  65. package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
  66. package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
  67. package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
  68. package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
  69. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
  70. package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
  71. package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
  72. package/lib/src/generated/api/SfuRoomInfo.js +1 -0
  73. package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
  74. package/lib/src/generated/api/SfuRoomParams.js +2 -0
  75. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
  76. package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
  77. package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
  78. package/lib/src/generated/api/SfuRoomRoster.js +2 -0
  79. package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
  80. package/lib/src/generated/api/SfuSendDataParams.js +2 -0
  81. package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
  82. package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
  83. package/lib/src/generated/api/SfuStatus.d.ts +24 -0
  84. package/lib/src/generated/api/SfuStatus.js +2 -0
  85. package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
  86. package/lib/src/generated/api/TrackMapEntry.js +2 -0
  87. package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
  88. package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
  89. package/lib/src/generated/api/index.d.ts +3 -0
  90. package/lib/src/index.d.ts +7 -0
  91. package/lib/src/index.js +4 -0
  92. package/lib/src/model/Ad4mModel.d.ts +84 -0
  93. package/lib/src/model/Ad4mModel.js +234 -4
  94. package/lib/src/model/ModelQueryBuilder.d.ts +16 -35
  95. package/lib/src/model/ModelQueryBuilder.js +88 -270
  96. package/lib/src/model/decorators.d.ts +32 -0
  97. package/lib/src/model/decorators.js +40 -1
  98. package/lib/src/model/shacl-gen.d.ts +3 -1
  99. package/lib/src/model/shacl-gen.js +13 -1
  100. package/lib/src/model/types.d.ts +7 -0
  101. package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
  102. package/lib/src/neighbourhood/MeshManager.js +1144 -0
  103. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
  104. package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
  105. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
  106. package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
  107. package/lib/src/neighbourhood/Session.d.ts +105 -0
  108. package/lib/src/neighbourhood/Session.js +412 -0
  109. package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
  110. package/lib/src/neighbourhood/SfuManager.js +619 -0
  111. package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
  112. package/lib/src/neighbourhood/SfuTypes.js +8 -0
  113. package/lib/src/perspectives/FlowInstance.d.ts +63 -24
  114. package/lib/src/perspectives/FlowInstance.js +74 -31
  115. package/lib/src/perspectives/FlowModels.d.ts +0 -16
  116. package/lib/src/perspectives/FlowModels.js +8 -16
  117. package/lib/src/perspectives/LiveQuery.d.ts +49 -0
  118. package/lib/src/perspectives/LiveQuery.js +169 -0
  119. package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
  120. package/lib/src/perspectives/PerspectiveClient.js +33 -36
  121. package/lib/src/perspectives/PerspectiveProxy.d.ts +67 -167
  122. package/lib/src/perspectives/PerspectiveProxy.js +121 -475
  123. package/lib/src/perspectives/TextContent.d.ts +31 -0
  124. package/lib/src/perspectives/TextContent.js +52 -0
  125. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -0
  126. package/lib/src/perspectives/WakerSubscriptionManager.js +58 -17
  127. package/lib/src/shacl/SHACLFlow.d.ts +7 -4
  128. package/lib/src/shacl/SHACLFlow.js +7 -4
  129. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  130. package/lib/src/shacl/SHACLShape.js +37 -0
  131. package/package.json +2 -2
  132. package/pnpm-workspace.yaml +4 -1
  133. package/src/Ad4mClient.test.ts +89 -17
  134. package/src/generated/api/AgentsByDidsRequest.ts +3 -0
  135. package/src/generated/api/CallSessionInfo.ts +20 -0
  136. package/src/generated/api/DiscardBatchRequest.ts +3 -0
  137. package/src/generated/api/Events.ts +14 -3
  138. package/src/generated/api/FlowStateChangedEvent.ts +36 -0
  139. package/src/generated/api/FlowStateEntry.ts +18 -0
  140. package/src/generated/api/IceServer.ts +19 -0
  141. package/src/generated/api/OnlineAgent.ts +6 -1
  142. package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
  143. package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
  144. package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
  145. package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
  146. package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
  147. package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
  148. package/src/generated/api/PerspectiveResynced.ts +7 -0
  149. package/src/generated/api/PerspectiveSubscribed.ts +8 -0
  150. package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
  151. package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
  152. package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
  153. package/src/generated/api/QueryUpdatesLagged.ts +7 -0
  154. package/src/generated/api/RemoveSubjectRequest.ts +7 -0
  155. package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
  156. package/src/generated/api/RpcMethods.ts +68 -8
  157. package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
  158. package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
  159. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  160. package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
  161. package/src/generated/api/SfuCascadePipe.ts +3 -0
  162. package/src/generated/api/SfuCascadeStatus.ts +7 -0
  163. package/src/generated/api/SfuConfig.ts +53 -0
  164. package/src/generated/api/SfuDataMessage.ts +23 -0
  165. package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
  166. package/src/generated/api/SfuMigrateEvent.ts +20 -0
  167. package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
  168. package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
  169. package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
  170. package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
  171. package/src/generated/api/SfuRoomInfo.ts +7 -0
  172. package/src/generated/api/SfuRoomParams.ts +3 -0
  173. package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
  174. package/src/generated/api/SfuRoomRoster.ts +12 -0
  175. package/src/generated/api/SfuSendDataParams.ts +7 -0
  176. package/src/generated/api/SfuSetConfigParams.ts +4 -0
  177. package/src/generated/api/SfuStatus.ts +24 -0
  178. package/src/generated/api/TrackMapEntry.ts +18 -0
  179. package/src/generated/api/UpdateSubjectRequest.ts +10 -0
  180. package/src/generated/api/index.ts +3 -0
  181. package/src/index.ts +7 -0
  182. package/src/model/Ad4mModel.test.ts +255 -231
  183. package/src/model/Ad4mModel.ts +271 -4
  184. package/src/model/ModelQueryBuilder.ts +103 -310
  185. package/src/model/abstract-classes.test.ts +225 -0
  186. package/src/model/decorators.ts +81 -0
  187. package/src/model/shacl-gen.ts +13 -0
  188. package/src/model/types.ts +7 -0
  189. package/src/neighbourhood/MeshManager.test.ts +2640 -0
  190. package/src/neighbourhood/MeshManager.ts +1350 -0
  191. package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
  192. package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
  193. package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
  194. package/src/neighbourhood/Session.test.ts +800 -0
  195. package/src/neighbourhood/Session.ts +525 -0
  196. package/src/neighbourhood/SfuManager.test.ts +677 -0
  197. package/src/neighbourhood/SfuManager.ts +803 -0
  198. package/src/neighbourhood/SfuTypes.ts +40 -0
  199. package/src/perspectives/FlowInstance.ts +108 -31
  200. package/src/perspectives/FlowModels.ts +8 -18
  201. package/src/perspectives/LiveQuery.test.ts +197 -0
  202. package/src/perspectives/LiveQuery.ts +189 -0
  203. package/src/perspectives/PerspectiveClient.ts +51 -51
  204. package/src/perspectives/PerspectiveProxy.test.ts +85 -401
  205. package/src/perspectives/PerspectiveProxy.ts +126 -536
  206. package/src/perspectives/TextContent.test.ts +123 -0
  207. package/src/perspectives/TextContent.ts +36 -0
  208. package/src/perspectives/WakerSubscriptionManager.test.ts +88 -6
  209. package/src/perspectives/WakerSubscriptionManager.ts +69 -18
  210. package/src/shacl/SHACLFlow.ts +7 -4
  211. package/src/shacl/SHACLShape.test.ts +2 -1
  212. package/src/shacl/SHACLShape.ts +49 -0
  213. package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
  214. package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
  215. package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
  216. package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
  217. package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
  218. package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
  219. /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
  220. /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
  221. /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
  222. /package/lib/src/generated/api/{PerspectiveSubscribeQueryResult.js → FlowStateChangedEvent.js} +0 -0
@@ -0,0 +1,189 @@
1
+ import type { PerspectiveClient } from "./PerspectiveClient";
2
+
3
+ /** Reply to `perspective.subscribeQuery` / `perspective.modelSubscribe`. */
4
+ export interface Subscribed {
5
+ subscriptionId: string
6
+ result: any
7
+ revision: number
8
+ }
9
+
10
+ /**
11
+ * A `query-subscription-update` event: the change from the previous revision.
12
+ * Model results carry `ids` (the new order), `upsert` (new or changed
13
+ * instances) and `totalCount`; query results carry `added` / `removed` rows;
14
+ * a result that could not be diffed comes whole as `result`.
15
+ */
16
+ export interface QueryUpdate {
17
+ subscriptionId: string
18
+ revision: number
19
+ ids?: string[]
20
+ upsert?: any[]
21
+ totalCount?: number
22
+ added?: any[]
23
+ removed?: any[]
24
+ result?: any
25
+ }
26
+
27
+ /** The executor dropped updates, maybe for any live query on this socket:
28
+ * every live query resyncs. */
29
+ export interface QueryLagged {
30
+ lagged: true
31
+ }
32
+
33
+ /** Apply one update to the last result. Query rows are a multiset: added rows are appended.
34
+ * Throws when the update names an instance that neither the last result nor
35
+ * the update holds: the last result was wrong, and the caller must resync. */
36
+ export function applyUpdate(result: any, update: QueryUpdate): any {
37
+ if ('result' in update) return update.result
38
+ if (update.ids) {
39
+ const byId = new Map<string, any>(result.instances.map((i: any) => [i.id, i]))
40
+ for (const instance of update.upsert!) byId.set(instance.id, instance)
41
+ const instances = update.ids.map(id => {
42
+ if (!byId.has(id)) throw new Error(`Live query update names unknown instance ${id}`)
43
+ return byId.get(id)
44
+ })
45
+ return { ...result, instances, totalCount: update.totalCount }
46
+ }
47
+ const toRemove = new Map<string, number>()
48
+ for (const row of update.removed!) {
49
+ const key = JSON.stringify(row)
50
+ toRemove.set(key, (toRemove.get(key) ?? 0) + 1)
51
+ }
52
+ const kept = (result as any[]).filter(row => {
53
+ const key = JSON.stringify(row)
54
+ const n = toRemove.get(key)
55
+ if (!n) return true
56
+ toRemove.set(key, n - 1)
57
+ return false
58
+ })
59
+ return [...kept, ...update.added!]
60
+ }
61
+
62
+ /**
63
+ * One live query on the executor. Holds the last result, applies each update
64
+ * to it, calls `resyncSubscription` when a revision is missing, and opens a
65
+ * new subscription after a reconnect (the executor ends a socket's
66
+ * subscriptions when it closes). `onResult` gets every result after the
67
+ * first; `start()` returns the first.
68
+ */
69
+ export class LiveQuery {
70
+ #client: PerspectiveClient
71
+ #uuid: string
72
+ #open: () => Promise<Subscribed>
73
+ #onResult: (result: any) => void
74
+ #id?: string
75
+ #revision = 0
76
+ #result: any
77
+ #started = false
78
+ #disposed = false
79
+ #generation = 0
80
+ #latest?: Promise<any>
81
+ // Updates that arrive while a subscribe or resync reply is outstanding.
82
+ #buffer: (QueryUpdate | QueryLagged)[] | null = null
83
+ #unlisten: () => void
84
+ #unreconnect: () => void
85
+
86
+ constructor(client: PerspectiveClient, uuid: string, open: () => Promise<Subscribed>, onResult: (result: any) => void) {
87
+ this.#client = client
88
+ this.#uuid = uuid
89
+ this.#open = open
90
+ this.#onResult = onResult
91
+ this.#unlisten = client.onQueryUpdate(update => this.#receive(update))
92
+ this.#unreconnect = client.onReconnect(() => {
93
+ this.start().catch(e => console.error('Error re-opening live query after reconnect:', e))
94
+ })
95
+ }
96
+
97
+ get id(): string | undefined { return this.#id }
98
+ get result(): any { return this.#result }
99
+
100
+ /** Open the subscription (again) and return its initial result. A start
101
+ * that a newer one overtakes resolves with the newer one's result. */
102
+ start(): Promise<any> {
103
+ this.#latest = this.#start(++this.#generation)
104
+ return this.#latest
105
+ }
106
+
107
+ async #start(generation: number): Promise<any> {
108
+ this.#buffer = []
109
+ let subscribed: Subscribed
110
+ try {
111
+ subscribed = await this.#open()
112
+ } catch (e) {
113
+ if (generation === this.#generation) this.#buffer = null
114
+ throw e
115
+ }
116
+ if (this.#disposed || generation !== this.#generation) {
117
+ this.#client.disposeQuerySubscription(this.#uuid, subscribed.subscriptionId).catch(() => {})
118
+ // Disposed while opening (e.g. a newer subscribe() on the same
119
+ // builder): the caller still gets the snapshot that was read.
120
+ return this.#disposed ? (this.#result ?? subscribed.result) : this.#latest
121
+ }
122
+ this.#id = subscribed.subscriptionId
123
+ this.#replace(subscribed.revision, subscribed.result)
124
+ return this.#result
125
+ }
126
+
127
+ dispose() {
128
+ this.#disposed = true
129
+ this.#generation++
130
+ this.#unlisten()
131
+ this.#unreconnect()
132
+ if (this.#id) this.#client.disposeQuerySubscription(this.#uuid, this.#id).catch(() => {})
133
+ }
134
+
135
+ /** Take `result` at `revision`, then apply the updates buffered meanwhile. */
136
+ #replace(revision: number, result: any) {
137
+ this.#revision = revision
138
+ this.#result = result
139
+ const buffered = this.#buffer ?? []
140
+ this.#buffer = null
141
+ if (this.#started) this.#onResult(result)
142
+ this.#started = true
143
+ for (const update of buffered) this.#receive(update)
144
+ }
145
+
146
+ #receive(update: QueryUpdate | QueryLagged) {
147
+ if (this.#buffer) {
148
+ this.#buffer.push(update)
149
+ return
150
+ }
151
+ if ('lagged' in update) {
152
+ if (this.#id) this.#resync()
153
+ return
154
+ }
155
+ if (update.subscriptionId !== this.#id || update.revision <= this.#revision) return
156
+ if (update.revision !== this.#revision + 1) {
157
+ this.#resync()
158
+ return
159
+ }
160
+ let result: any
161
+ try {
162
+ result = applyUpdate(this.#result, update)
163
+ } catch {
164
+ this.#resync()
165
+ return
166
+ }
167
+ this.#revision = update.revision
168
+ this.#result = result
169
+ this.#onResult(this.#result)
170
+ }
171
+
172
+ #resync() {
173
+ const generation = this.#generation
174
+ const id = this.#id!
175
+ this.#buffer = []
176
+ this.#client.resyncSubscription(this.#uuid, id).then(
177
+ ({ revision, result }) => {
178
+ if (!this.#disposed && generation === this.#generation) this.#replace(revision, result)
179
+ },
180
+ () => {
181
+ // Replace the subscription with a new one.
182
+ if (!this.#disposed && generation === this.#generation) {
183
+ this.#client.disposeQuerySubscription(this.#uuid, id).catch(() => {})
184
+ this.start().catch(e => console.error('Error re-opening live query:', e))
185
+ }
186
+ },
187
+ )
188
+ }
189
+ }
@@ -13,7 +13,7 @@ import { Perspective } from "./Perspective";
13
13
  import { PerspectiveHandle } from "./PerspectiveHandle";
14
14
  import { LinkStatus, PerspectiveProxy } from './PerspectiveProxy';
15
15
  import { AIClient } from "../ai/AIClient";
16
- import { AllInstancesResult } from "../model/types";
16
+ import type { QueryLagged, QueryUpdate, Subscribed } from "./LiveQuery";
17
17
  import type { TranscriptTurn } from "../generated/api";
18
18
  import type { PerspectiveQueryLinksParams } from "../generated/api/PerspectiveQueryLinksParams";
19
19
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
@@ -24,21 +24,13 @@ import type { AddAutoProcessorConfig, InterpretationOverlayInfo, RawScope, RunIn
24
24
  // would otherwise be a cycle).
25
25
  import type {
26
26
  FlowFireOutcome, FlowMintedReceipt, FlowOutputRef, FlowProposeResult,
27
- FlowReceiptVerdict, FlowValidOutput,
27
+ FlowReceiptVerdict, FlowStateEntry, FlowValidOutput,
28
28
  } from "./FlowInstance";
29
29
 
30
- function normalizeQueryResult(raw: unknown, errorContext: string): AllInstancesResult {
31
- let finalResult: unknown = raw
32
30
 
33
- if (typeof finalResult === 'string') {
34
- try {
35
- finalResult = JSON.parse(finalResult)
36
- } catch (e) {
37
- console.error(errorContext, e)
38
- }
39
- }
40
-
41
- return finalResult as AllInstancesResult
31
+ /** The wire form of a model query's classes: `class_name` for one, `class_names` for a union. */
32
+ function classParams(className: string | string[]): { class_name: string } | { class_names: string[] } {
33
+ return Array.isArray(className) ? { class_names: className } : { class_name: className }
42
34
  }
43
35
 
44
36
  export class PerspectiveClient {
@@ -114,51 +106,33 @@ export class PerspectiveClient {
114
106
  return JSON.parse(result) as T
115
107
  }
116
108
 
117
- async subscribeQuery(uuid: string, query: string): Promise<{ subscriptionId: string, result: AllInstancesResult }> {
118
- const response = await this.#apiClient.call(
119
- 'perspective.subscribeQuery', { uuid, query }
120
- )
121
- const { subscriptionId, result } = response
122
- const parsed = normalizeQueryResult(result, 'Error parsing subscribeQuery result:')
123
- return { subscriptionId, result: parsed }
109
+ /** Open a live SPARQL query. Updates arrive through {@link onQueryUpdate}. */
110
+ async subscribeQuery(uuid: string, query: string): Promise<Subscribed> {
111
+ return this.#apiClient.call('perspective.subscribeQuery', { uuid, query })
124
112
  }
125
113
 
126
- async perspectiveKeepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean> {
127
- return this.#apiClient.call(
128
- 'perspective.keepAliveQuery', { uuid, subscriptionId }
129
- )
114
+ /** Every `query-subscription-update` event on this client's socket. */
115
+ onQueryUpdate(cb: (update: QueryUpdate | QueryLagged) => void): () => void {
116
+ return this.#apiClient.on('query-subscription-update', cb)
130
117
  }
131
118
 
132
- async perspectiveDisposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean> {
133
- return this.#apiClient.call(
134
- 'perspective.disposeQuery', { uuid, subscriptionId }
135
- )
136
- }
137
-
138
- subscribeToQueryUpdates(subscriptionId: string, onData: (result: AllInstancesResult) => void): () => void {
139
- return this.#apiClient.on('query-subscription-update', (event) => {
140
- if (event.subscriptionId !== subscriptionId) return
141
- onData(normalizeQueryResult(event.result, 'Error parsing query subscription:'))
142
- })
143
- }
144
-
145
- async keepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean> {
146
- return this.#apiClient.call(
147
- 'perspective.keepAliveQuery', { uuid, subscriptionId }
148
- )
119
+ /** The current result and revision of a live query, after a revision gap. */
120
+ async resyncSubscription(uuid: string, subscriptionId: string): Promise<{ revision: number, result: any }> {
121
+ return this.#apiClient.call('perspective.resyncSubscription', { uuid, subscriptionId })
149
122
  }
150
123
 
151
124
  /** Ends the subscription on the executor. The caller releases its local listener
152
- * with the function `subscribeToQueryUpdates` returned. */
125
+ * with the function {@link onQueryUpdate} returned. */
153
126
  async disposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean> {
154
127
  return this.#apiClient.call(
155
128
  'perspective.disposeQuery', { uuid, subscriptionId }
156
129
  )
157
130
  }
158
131
 
159
- async modelQuery(uuid: string, className: string, queryJson: string, options?: CallOptions): Promise<any> {
132
+ /** `className` may name several classes: one query over their union (#1238). */
133
+ async modelQuery(uuid: string, className: string | string[], queryJson: string, options?: CallOptions): Promise<any> {
160
134
  const resultJson = await this.#apiClient.call(
161
- 'perspective.modelQuery', { uuid, class_name: className, query_json: queryJson }, options
135
+ 'perspective.modelQuery', { uuid, ...classParams(className), query_json: queryJson }, options
162
136
  )
163
137
  return JSON.parse(resultJson)
164
138
  }
@@ -186,14 +160,11 @@ export class PerspectiveClient {
186
160
  return JSON.parse(resultJson)
187
161
  }
188
162
 
189
- async modelSubscribe(uuid: string, className: string, queryJson: string): Promise<{ subscriptionId: string, result: any }> {
190
- const response = await this.#apiClient.call(
191
- 'perspective.modelSubscribe', { uuid, class_name: className, query_json: queryJson }
163
+ /** Open a live model query over one class or several. Updates arrive through {@link onQueryUpdate}. */
164
+ async modelSubscribe(uuid: string, className: string | string[], queryJson: string): Promise<Subscribed> {
165
+ return this.#apiClient.call(
166
+ 'perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson }
192
167
  )
193
- return {
194
- subscriptionId: response.subscription_id,
195
- result: JSON.parse(response.result)
196
- }
197
168
  }
198
169
 
199
170
  async add(name: string): Promise<PerspectiveProxy> {
@@ -416,6 +387,22 @@ export class PerspectiveClient {
416
387
  )
417
388
  }
418
389
 
390
+ /** The calling agent's recorded state of each flow instance it has
391
+ * derived, optionally narrowed to `instances`. */
392
+ async flowStates(uuid: string, instances?: string[]): Promise<FlowStateEntry[]> {
393
+ return this.#apiClient.call(
394
+ 'perspective.flowStates', { uuid, instances },
395
+ )
396
+ }
397
+
398
+ /** The proposals of `instance` the calling agent's replica recorded as
399
+ * fired, sorted. */
400
+ async flowFired(uuid: string, instance: string): Promise<string[]> {
401
+ return this.#apiClient.call(
402
+ 'perspective.flowFired', { uuid, instance },
403
+ )
404
+ }
405
+
419
406
  /** Mint and store the receipt for a completed flow run. Fails while the
420
407
  * run has not settled into a terminal state, and when an output's
421
408
  * content no longer matches what the quorum committed to. */
@@ -472,6 +459,19 @@ export class PerspectiveClient {
472
459
  )
473
460
  }
474
461
 
462
+ /** Through an abstract class (#1435), the executor writes to the record's own classes. */
463
+ async updateSubject(uuid: string, subjectClass: string, expressionAddress: string, values: string, batchId?: string): Promise<boolean> {
464
+ return this.#apiClient.call(
465
+ 'perspective.updateSubject', { uuid, subjectClass, expressionAddress, values, batchId }
466
+ )
467
+ }
468
+
469
+ async removeSubject(uuid: string, subjectClass: string, expressionAddress: string, batchId?: string): Promise<boolean> {
470
+ return this.#apiClient.call(
471
+ 'perspective.removeSubject', { uuid, subjectClass, expressionAddress, batchId }
472
+ )
473
+ }
474
+
475
475
  async getSubjectData(uuid: string, subjectClass: string, expressionAddress: string): Promise<string> {
476
476
  return this.#apiClient.call(
477
477
  'perspective.getSubjectData', { uuid, subjectClass, expressionAddress }