@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
@@ -6,12 +6,18 @@
6
6
  * Wraps two on-graph objects:
7
7
  *
8
8
  * - `FlowInstanceRecord` — the raw @Model row minted by
9
- * {@link FlowInstance.start}; carries `flow`, `subject`, `currentState`,
10
- * and Ad4mModel's synthesised `createdAt`.
9
+ * {@link FlowInstance.start}; carries `flowUri`, `subject` and
10
+ * Ad4mModel's synthesised `createdAt`. Not the state: see below.
11
11
  * - `SHACLFlow` — the flow definition the record is bound to. Held so
12
12
  * `availableTransitions` / `currentState` object lookups don't require
13
13
  * a per-call round-trip.
14
14
  *
15
+ * The state is derived by the executor from the signed proposals and kept
16
+ * per agent outside the graph (#1424). The factories read it with one
17
+ * batched `PerspectiveProxy.flowStates` call, so `currentStateName` is the
18
+ * state as **this agent's** executor last derived it, at load time.
19
+ * Subscribe with `PerspectiveProxy.onFlowStateChanged` to follow it.
20
+ *
15
21
  * Construct via the class factories — {@link FlowInstance.start} for the
16
22
  * mint path and {@link FlowInstance.findAll} for the read path — rather
17
23
  * than the `wrap` escape hatch, which exists for tests that already own
@@ -23,7 +29,7 @@
23
29
  * - `uri`, `subject`, `flowName`, `currentStateName`, `startedAtMillis`
24
30
  * accessors.
25
31
  * - `currentState` — resolves the `FlowState` on the shape whose name
26
- * matches `record.currentState`.
32
+ * matches `currentStateName`.
27
33
  * - `availableTransitions` — filters `shape.transitions` by `fromState`.
28
34
  * - `proposals()` — queries `FlowTransitionProposal` records that
29
35
  * target this instance's URI.
@@ -41,9 +47,9 @@
41
47
  * Its `FlowProposeResult` is what tells queued from no-op from stalled.
42
48
  *
43
49
  * Still absent (rather than shipped as `throw new Error("not yet")`
44
- * stubs): `fireAction`, and the subscriptions (`onStateChange`,
45
- * `onProposalAdded`, `onProposalResolved`) — they land with the
46
- * subscription-topic slice.
50
+ * stubs): `fireAction`, and per-instance subscriptions (`onProposalAdded`,
51
+ * `onProposalResolved`). State changes are perspective-wide:
52
+ * `PerspectiveProxy.onFlowStateChanged`.
47
53
  *
48
54
  * ## The guard-free rule
49
55
  *
@@ -58,6 +64,18 @@ import { PerspectiveProxy } from "./PerspectiveProxy";
58
64
  import { FlowInstanceRecord, FlowTransitionProposal } from "./FlowModels";
59
65
  import { SHACLFlow, FlowState, FlowTransition } from "../shacl/SHACLFlow";
60
66
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
67
+ /** One instance this agent's executor keeps bookkeeping for — an entry of
68
+ * `PerspectiveProxy.flowStates()`. An instance with no entry has never been
69
+ * derived nor minted by this agent here. */
70
+ export interface FlowStateEntry {
71
+ instance: string;
72
+ /** The state this agent's executor last derived, or `null` for an instance
73
+ * this agent minted here and has not derived yet: it stands at its flow's
74
+ * first state. */
75
+ currentState: string | null;
76
+ /** RFC 3339 time of the derivation that wrote `currentState`; `null` with it. */
77
+ derivedAt: string | null;
78
+ }
61
79
  /** One fired flow transition, as returned by {@link FlowInstance.acceptProposal}
62
80
  * (and, engine-side, by every consensus pass). */
63
81
  export interface FlowFireOutcome {
@@ -172,19 +190,28 @@ export declare class FlowInstance {
172
190
  /** The flow definition this instance was minted against. */
173
191
  readonly shape: SHACLFlow;
174
192
  /**
175
- * The on-graph record — carries `flow`, `subject`, `currentState`
176
- * and Ad4mModel's synthesised `createdAt`. Callers can reach into it
177
- * for anything the wrapper doesn't expose directly, but should prefer
178
- * the wrapper accessors so future refactors of the underlying shape
179
- * don't ripple through their code.
193
+ * The on-graph record — carries `flowUri`, `subject` and Ad4mModel's
194
+ * synthesised `createdAt`. Callers can reach into it for anything the
195
+ * wrapper doesn't expose directly, but should prefer the wrapper
196
+ * accessors so future refactors of the underlying shape don't ripple
197
+ * through their code.
180
198
  */
181
199
  readonly record: FlowInstanceRecord;
200
+ /** See {@link currentStateName}. */
201
+ private readonly stateName;
182
202
  /**
183
203
  * Private constructor — construct via {@link FlowInstance.start} or
184
204
  * {@link FlowInstance.findAll}. {@link FlowInstance.wrap} is the
185
205
  * escape hatch for tests / direct construction cases.
186
206
  */
187
207
  private constructor();
208
+ /** The state to show for `record`, from this agent's `flowStates` entries:
209
+ * the recorded derivation; the flow's first state for an instance this
210
+ * agent minted and has not derived yet; `undefined` for one with no entry
211
+ * — synced in, and not derived by this agent yet. */
212
+ private static stateOf;
213
+ /** One `flowStates` round-trip for every record in `records`. */
214
+ private static recordedStates;
188
215
  /**
189
216
  * Escape hatch used by {@link FlowInstance.start} and
190
217
  * {@link FlowInstance.findAll} — not meant for general use, but public
@@ -192,7 +219,7 @@ export declare class FlowInstance {
192
219
  * (e.g. from pre-populated fixtures) can build a wrapper without
193
220
  * going through the mint path.
194
221
  */
195
- static wrap(perspective: PerspectiveProxy, shape: SHACLFlow, record: FlowInstanceRecord): FlowInstance;
222
+ static wrap(perspective: PerspectiveProxy, shape: SHACLFlow, record: FlowInstanceRecord, currentStateName?: string): FlowInstance;
196
223
  /**
197
224
  * Start `flowName` on `baseExpression`: mint a new `FlowInstance` on the
198
225
  * given perspective (design doc §4.3), or return the one already running
@@ -211,13 +238,12 @@ export declare class FlowInstance {
211
238
  * on-graph record, so `currentState` / `availableTransitions` /
212
239
  * `proposals` accessors work without further round-trips.
213
240
  *
214
- * The record's `currentState` is a per-replica cache the consensus engine
215
- * writes as a local link. It is read back only for display — the cache-first
216
- * path in `gather_active_flow_contexts` fills the state rendered into LLM
217
- * context — and **never as authority**: anything that decides something
218
- * (the fold, the mint pass) derives state from the signed links present now
219
- * and does not consult the cache. Treat it as a display hint, not as the
220
- * flow's state.
241
+ * `currentStateName` is the state this agent's executor last derived
242
+ * (`PerspectiveProxy.flowStates`) — a display value, **never authority**:
243
+ * anything that decides something (the fold, the mint pass) derives state
244
+ * from the signed links present now. A run started by this call stands at
245
+ * the flow's first state; an existing run this agent has not derived yet
246
+ * reads `undefined` (see {@link currentStateName}).
221
247
  *
222
248
  * @param perspective - The perspective the flow instance lives on
223
249
  * @param flowName - Name of a `SHACLFlow` already registered on the perspective
@@ -292,8 +318,19 @@ export declare class FlowInstance {
292
318
  get flowName(): string;
293
319
  /** Flow URI — the on-graph discriminator, collision-free across modules. */
294
320
  get flowUri(): string;
295
- /** Name of the state this instance is currently in. */
296
- get currentStateName(): string;
321
+ /**
322
+ * Name of the state this instance is in, as this agent's executor last
323
+ * derived it when the wrapper was loaded (`PerspectiveProxy.flowStates`).
324
+ * An instance this agent minted and has not derived yet reads as its
325
+ * flow's first state.
326
+ *
327
+ * `undefined` means **not derived by this agent yet**: the run synced in
328
+ * (or the executor was upgraded) and no pass of this agent's has covered it.
329
+ * Show it as pending, not as the first state. The catch-up pass that
330
+ * derives it publishes `flow-state-changed` with `caughtUp: true`. A
331
+ * snapshot: reload, or follow `PerspectiveProxy.onFlowStateChanged`.
332
+ */
333
+ get currentStateName(): string | undefined;
297
334
  /**
298
335
  * ISO-8601 (epoch millis after Ad4mModel hydration) start time.
299
336
  * Returns `undefined` when hydration didn't produce a `createdAt`
@@ -301,17 +338,19 @@ export declare class FlowInstance {
301
338
  */
302
339
  get startedAtMillis(): number | undefined;
303
340
  /**
304
- * The `FlowState` object on the shape matching `currentStateName`.
341
+ * The `FlowState` object on the shape matching `currentStateName`, or
342
+ * `undefined` when that is (not derived by this agent yet).
305
343
  * Throws when the record's state name is not declared on the flow —
306
344
  * that's a "stale FlowInstance whose flow was edited under it" bug,
307
345
  * not a silent-fail case.
308
346
  */
309
- get currentState(): FlowState;
347
+ get currentState(): FlowState | undefined;
310
348
  /**
311
349
  * Every `FlowTransition` on the shape whose `fromState` matches
312
350
  * `currentStateName`. Order preserved from the shape.
313
351
  *
314
- * Empty when the current state is terminal (no outgoing transitions).
352
+ * Empty when the current state is terminal (no outgoing transitions), or
353
+ * not derived by this agent yet.
315
354
  */
316
355
  get availableTransitions(): FlowTransition[];
317
356
  /**
@@ -6,12 +6,18 @@
6
6
  * Wraps two on-graph objects:
7
7
  *
8
8
  * - `FlowInstanceRecord` — the raw @Model row minted by
9
- * {@link FlowInstance.start}; carries `flow`, `subject`, `currentState`,
10
- * and Ad4mModel's synthesised `createdAt`.
9
+ * {@link FlowInstance.start}; carries `flowUri`, `subject` and
10
+ * Ad4mModel's synthesised `createdAt`. Not the state: see below.
11
11
  * - `SHACLFlow` — the flow definition the record is bound to. Held so
12
12
  * `availableTransitions` / `currentState` object lookups don't require
13
13
  * a per-call round-trip.
14
14
  *
15
+ * The state is derived by the executor from the signed proposals and kept
16
+ * per agent outside the graph (#1424). The factories read it with one
17
+ * batched `PerspectiveProxy.flowStates` call, so `currentStateName` is the
18
+ * state as **this agent's** executor last derived it, at load time.
19
+ * Subscribe with `PerspectiveProxy.onFlowStateChanged` to follow it.
20
+ *
15
21
  * Construct via the class factories — {@link FlowInstance.start} for the
16
22
  * mint path and {@link FlowInstance.findAll} for the read path — rather
17
23
  * than the `wrap` escape hatch, which exists for tests that already own
@@ -23,7 +29,7 @@
23
29
  * - `uri`, `subject`, `flowName`, `currentStateName`, `startedAtMillis`
24
30
  * accessors.
25
31
  * - `currentState` — resolves the `FlowState` on the shape whose name
26
- * matches `record.currentState`.
32
+ * matches `currentStateName`.
27
33
  * - `availableTransitions` — filters `shape.transitions` by `fromState`.
28
34
  * - `proposals()` — queries `FlowTransitionProposal` records that
29
35
  * target this instance's URI.
@@ -41,9 +47,9 @@
41
47
  * Its `FlowProposeResult` is what tells queued from no-op from stalled.
42
48
  *
43
49
  * Still absent (rather than shipped as `throw new Error("not yet")`
44
- * stubs): `fireAction`, and the subscriptions (`onStateChange`,
45
- * `onProposalAdded`, `onProposalResolved`) — they land with the
46
- * subscription-topic slice.
50
+ * stubs): `fireAction`, and per-instance subscriptions (`onProposalAdded`,
51
+ * `onProposalResolved`). State changes are perspective-wide:
52
+ * `PerspectiveProxy.onFlowStateChanged`.
47
53
  *
48
54
  * ## The guard-free rule
49
55
  *
@@ -86,16 +92,35 @@ export class FlowInstance {
86
92
  /** The flow definition this instance was minted against. */
87
93
  shape,
88
94
  /**
89
- * The on-graph record — carries `flow`, `subject`, `currentState`
90
- * and Ad4mModel's synthesised `createdAt`. Callers can reach into it
91
- * for anything the wrapper doesn't expose directly, but should prefer
92
- * the wrapper accessors so future refactors of the underlying shape
93
- * don't ripple through their code.
95
+ * The on-graph record — carries `flowUri`, `subject` and Ad4mModel's
96
+ * synthesised `createdAt`. Callers can reach into it for anything the
97
+ * wrapper doesn't expose directly, but should prefer the wrapper
98
+ * accessors so future refactors of the underlying shape don't ripple
99
+ * through their code.
94
100
  */
95
- record) {
101
+ record,
102
+ /** See {@link currentStateName}. */
103
+ stateName) {
96
104
  this.perspective = perspective;
97
105
  this.shape = shape;
98
106
  this.record = record;
107
+ this.stateName = stateName;
108
+ }
109
+ /** The state to show for `record`, from this agent's `flowStates` entries:
110
+ * the recorded derivation; the flow's first state for an instance this
111
+ * agent minted and has not derived yet; `undefined` for one with no entry
112
+ * — synced in, and not derived by this agent yet. */
113
+ static stateOf(shape, record, recorded) {
114
+ if (!recorded.has(record.id))
115
+ return undefined;
116
+ return recorded.get(record.id) ?? shape.states[0]?.name;
117
+ }
118
+ /** One `flowStates` round-trip for every record in `records`. */
119
+ static async recordedStates(perspective, records) {
120
+ if (records.length === 0)
121
+ return new Map();
122
+ const entries = await perspective.flowStates(records.map((r) => r.id));
123
+ return new Map(entries.map((e) => [e.instance, e.currentState]));
99
124
  }
100
125
  /**
101
126
  * Escape hatch used by {@link FlowInstance.start} and
@@ -104,8 +129,8 @@ export class FlowInstance {
104
129
  * (e.g. from pre-populated fixtures) can build a wrapper without
105
130
  * going through the mint path.
106
131
  */
107
- static wrap(perspective, shape, record) {
108
- return new FlowInstance(perspective, shape, record);
132
+ static wrap(perspective, shape, record, currentStateName) {
133
+ return new FlowInstance(perspective, shape, record, currentStateName ?? FlowInstance.stateOf(shape, record, new Map()));
109
134
  }
110
135
  /**
111
136
  * Start `flowName` on `baseExpression`: mint a new `FlowInstance` on the
@@ -125,13 +150,12 @@ export class FlowInstance {
125
150
  * on-graph record, so `currentState` / `availableTransitions` /
126
151
  * `proposals` accessors work without further round-trips.
127
152
  *
128
- * The record's `currentState` is a per-replica cache the consensus engine
129
- * writes as a local link. It is read back only for display — the cache-first
130
- * path in `gather_active_flow_contexts` fills the state rendered into LLM
131
- * context — and **never as authority**: anything that decides something
132
- * (the fold, the mint pass) derives state from the signed links present now
133
- * and does not consult the cache. Treat it as a display hint, not as the
134
- * flow's state.
153
+ * `currentStateName` is the state this agent's executor last derived
154
+ * (`PerspectiveProxy.flowStates`) — a display value, **never authority**:
155
+ * anything that decides something (the fold, the mint pass) derives state
156
+ * from the signed links present now. A run started by this call stands at
157
+ * the flow's first state; an existing run this agent has not derived yet
158
+ * reads `undefined` (see {@link currentStateName}).
135
159
  *
136
160
  * @param perspective - The perspective the flow instance lives on
137
161
  * @param flowName - Name of a `SHACLFlow` already registered on the perspective
@@ -174,16 +198,18 @@ export class FlowInstance {
174
198
  return typeof v === "number" ? v : Number.POSITIVE_INFINITY;
175
199
  };
176
200
  const [first] = [...existing].sort((a, b) => startedAt(a) - startedAt(b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
177
- return FlowInstance.wrap(perspective, flow, first);
201
+ const recorded = await FlowInstance.recordedStates(perspective, [first]);
202
+ return FlowInstance.wrap(perspective, flow, first, FlowInstance.stateOf(flow, first, recorded));
178
203
  }
179
204
  // Store the flow's URI, not the bare name — see FlowInstanceRecord's
180
205
  // docstring for the collision-across-modules argument (James PR #929 R5).
206
+ // No state on the record: the executor seeds this agent's bookkeeping
207
+ // from this write, so its first settle is reported (#1424).
181
208
  const record = await FlowInstanceRecord.create(perspective, {
182
209
  flowUri: flow.flowUri,
183
210
  subject: baseExpression,
184
- currentState: flow.states[0].name,
185
211
  });
186
- return FlowInstance.wrap(perspective, flow, record);
212
+ return FlowInstance.wrap(perspective, flow, record, flow.states[0].name);
187
213
  }
188
214
  /**
189
215
  * Return every live `FlowInstance` on the perspective (design doc §4.3).
@@ -278,7 +304,7 @@ export class FlowInstance {
278
304
  // means stripping the namespace + the `Flow` suffix. Records that
279
305
  // don't parse this way are treated as stale and skipped.
280
306
  const shapesByUri = new Map();
281
- const wrappers = [];
307
+ const paired = [];
282
308
  for (const record of records) {
283
309
  let shape = shapesByUri.get(record.flowUri);
284
310
  if (!shape) {
@@ -294,9 +320,11 @@ export class FlowInstance {
294
320
  shape = loaded;
295
321
  shapesByUri.set(record.flowUri, shape);
296
322
  }
297
- wrappers.push(FlowInstance.wrap(perspective, shape, record));
323
+ paired.push([record, shape]);
298
324
  }
299
- return wrappers;
325
+ // Every state in one round-trip, not one per instance.
326
+ const recorded = await FlowInstance.recordedStates(perspective, paired.map(([record]) => record));
327
+ return paired.map(([record, shape]) => FlowInstance.wrap(perspective, shape, record, FlowInstance.stateOf(shape, record, recorded)));
300
328
  }
301
329
  // ── Read accessors ────────────────────────────────────────────────────
302
330
  /**
@@ -329,9 +357,20 @@ export class FlowInstance {
329
357
  get flowUri() {
330
358
  return this.record.flowUri;
331
359
  }
332
- /** Name of the state this instance is currently in. */
360
+ /**
361
+ * Name of the state this instance is in, as this agent's executor last
362
+ * derived it when the wrapper was loaded (`PerspectiveProxy.flowStates`).
363
+ * An instance this agent minted and has not derived yet reads as its
364
+ * flow's first state.
365
+ *
366
+ * `undefined` means **not derived by this agent yet**: the run synced in
367
+ * (or the executor was upgraded) and no pass of this agent's has covered it.
368
+ * Show it as pending, not as the first state. The catch-up pass that
369
+ * derives it publishes `flow-state-changed` with `caughtUp: true`. A
370
+ * snapshot: reload, or follow `PerspectiveProxy.onFlowStateChanged`.
371
+ */
333
372
  get currentStateName() {
334
- return this.record.currentState;
373
+ return this.stateName;
335
374
  }
336
375
  /**
337
376
  * ISO-8601 (epoch millis after Ad4mModel hydration) start time.
@@ -343,12 +382,15 @@ export class FlowInstance {
343
382
  return typeof v === "number" ? v : undefined;
344
383
  }
345
384
  /**
346
- * The `FlowState` object on the shape matching `currentStateName`.
385
+ * The `FlowState` object on the shape matching `currentStateName`, or
386
+ * `undefined` when that is (not derived by this agent yet).
347
387
  * Throws when the record's state name is not declared on the flow —
348
388
  * that's a "stale FlowInstance whose flow was edited under it" bug,
349
389
  * not a silent-fail case.
350
390
  */
351
391
  get currentState() {
392
+ if (this.currentStateName === undefined)
393
+ return undefined;
352
394
  const s = this.shape.states.find((x) => x.name === this.currentStateName);
353
395
  if (!s) {
354
396
  throw new Error(`FlowInstance ${this.uri}: currentState "${this.currentStateName}" is not declared on flow "${this.flowName}". ` +
@@ -360,7 +402,8 @@ export class FlowInstance {
360
402
  * Every `FlowTransition` on the shape whose `fromState` matches
361
403
  * `currentStateName`. Order preserved from the shape.
362
404
  *
363
- * Empty when the current state is terminal (no outgoing transitions).
405
+ * Empty when the current state is terminal (no outgoing transitions), or
406
+ * not derived by this agent yet.
364
407
  */
365
408
  get availableTransitions() {
366
409
  return this.shape.transitions.filter((t) => t.fromState === this.currentStateName);
@@ -116,14 +116,6 @@ export declare class FlowTransitionProposal extends Ad4mModel {
116
116
  * Read-only: vote with `acceptProposal`, withdraw with `rejectProposal`.
117
117
  */
118
118
  acceptedBy: string[];
119
- /**
120
- * `"fired"` once this replica's consensus pass has recorded the transition
121
- * this proposal settled. Per-replica bookkeeping, never an input to the
122
- * engine's own derivation. Only this replica's own `Local` mark is read:
123
- * a Shared one a peer wrote says nothing about what happened here.
124
- * Read-only.
125
- */
126
- resolvedAs?: string;
127
119
  }
128
120
  export declare class FlowInstanceRecord extends Ad4mModel {
129
121
  /**
@@ -151,12 +143,4 @@ export declare class FlowInstanceRecord extends Ad4mModel {
151
143
  * on read.
152
144
  */
153
145
  subject: string;
154
- /**
155
- * The state name this replica's executor last derived for the flow — a
156
- * per-replica cache written as a `local` link, never the authority (the
157
- * fold over the signed proposals is). Optional on the shape: a row that
158
- * synced in from a peer carries no value until the local consensus pass
159
- * has run, so an empty string means "not yet derived here".
160
- */
161
- currentState: string;
162
146
  }
@@ -125,6 +125,10 @@ let FlowTransitionProposal = class FlowTransitionProposal extends Ad4mModel {
125
125
  * Read-only: vote with `acceptProposal`, withdraw with `rejectProposal`.
126
126
  */
127
127
  this.acceptedBy = [];
128
+ // Whether this proposal settled an edge is not on the record: the
129
+ // executor keeps that per agent, outside the graph (#1424). Ask
130
+ // `PerspectiveProxy.flowFired(instance)` for the proposals your replica
131
+ // recorded as fired, or listen with `onFlowStateChanged`.
128
132
  // "When was this proposal written?" is answered by `Ad4mModel`'s built-in
129
133
  // `createdAt`, synthesized on hydration from the earliest link timestamp
130
134
  // of the proposal's own links (all written together during create_subject).
@@ -178,10 +182,6 @@ __decorate([
178
182
  HasMany({ through: "ad4m://acceptedBy", getter: ACCEPTED_BY_GETTER, readOnly: true }),
179
183
  __metadata("design:type", Array)
180
184
  ], FlowTransitionProposal.prototype, "acceptedBy", void 0);
181
- __decorate([
182
- Optional({ through: "ad4m://flow/resolved_as", readOnly: true, local: true }),
183
- __metadata("design:type", String)
184
- ], FlowTransitionProposal.prototype, "resolvedAs", void 0);
185
185
  FlowTransitionProposal = __decorate([
186
186
  Model({ name: "FlowTransitionProposal" })
187
187
  ], FlowTransitionProposal);
@@ -234,14 +234,10 @@ let FlowInstanceRecord = class FlowInstanceRecord extends Ad4mModel {
234
234
  * on read.
235
235
  */
236
236
  this.subject = "";
237
- /**
238
- * The state name this replica's executor last derived for the flow — a
239
- * per-replica cache written as a `local` link, never the authority (the
240
- * fold over the signed proposals is). Optional on the shape: a row that
241
- * synced in from a peer carries no value until the local consensus pass
242
- * has run, so an empty string means "not yet derived here".
243
- */
244
- this.currentState = "";
237
+ // The flow's state is not on the record. It is derived from the signed
238
+ // proposals, and each agent's executor keeps what it last derived outside
239
+ // the graph (#1424): read it with `PerspectiveProxy.flowStates`, or use
240
+ // the `FlowInstance` wrapper, whose `currentStateName` is filled from it.
245
241
  // "When was this flow started?" is answered by `Ad4mModel`'s built-in
246
242
  // `createdAt`, synthesized on hydration from the earliest link timestamp
247
243
  // of the instance's own links (all written together during `mint_flow_instance`).
@@ -255,10 +251,6 @@ __decorate([
255
251
  Property({ through: "ad4m://flow/base", required: true }),
256
252
  __metadata("design:type", String)
257
253
  ], FlowInstanceRecord.prototype, "subject", void 0);
258
- __decorate([
259
- Property({ through: "ad4m://flow/current_state", local: true }),
260
- __metadata("design:type", String)
261
- ], FlowInstanceRecord.prototype, "currentState", void 0);
262
254
  FlowInstanceRecord = __decorate([
263
255
  Model({ name: "FlowInstance" })
264
256
  ], FlowInstanceRecord);
@@ -0,0 +1,49 @@
1
+ import type { PerspectiveClient } from "./PerspectiveClient";
2
+ /** Reply to `perspective.subscribeQuery` / `perspective.modelSubscribe`. */
3
+ export interface Subscribed {
4
+ subscriptionId: string;
5
+ result: any;
6
+ revision: number;
7
+ }
8
+ /**
9
+ * A `query-subscription-update` event: the change from the previous revision.
10
+ * Model results carry `ids` (the new order), `upsert` (new or changed
11
+ * instances) and `totalCount`; query results carry `added` / `removed` rows;
12
+ * a result that could not be diffed comes whole as `result`.
13
+ */
14
+ export interface QueryUpdate {
15
+ subscriptionId: string;
16
+ revision: number;
17
+ ids?: string[];
18
+ upsert?: any[];
19
+ totalCount?: number;
20
+ added?: any[];
21
+ removed?: any[];
22
+ result?: any;
23
+ }
24
+ /** The executor dropped updates, maybe for any live query on this socket:
25
+ * every live query resyncs. */
26
+ export interface QueryLagged {
27
+ lagged: true;
28
+ }
29
+ /** Apply one update to the last result. Query rows are a multiset: added rows are appended.
30
+ * Throws when the update names an instance that neither the last result nor
31
+ * the update holds: the last result was wrong, and the caller must resync. */
32
+ export declare function applyUpdate(result: any, update: QueryUpdate): any;
33
+ /**
34
+ * One live query on the executor. Holds the last result, applies each update
35
+ * to it, calls `resyncSubscription` when a revision is missing, and opens a
36
+ * new subscription after a reconnect (the executor ends a socket's
37
+ * subscriptions when it closes). `onResult` gets every result after the
38
+ * first; `start()` returns the first.
39
+ */
40
+ export declare class LiveQuery {
41
+ #private;
42
+ constructor(client: PerspectiveClient, uuid: string, open: () => Promise<Subscribed>, onResult: (result: any) => void);
43
+ get id(): string | undefined;
44
+ get result(): any;
45
+ /** Open the subscription (again) and return its initial result. A start
46
+ * that a newer one overtakes resolves with the newer one's result. */
47
+ start(): Promise<any>;
48
+ dispose(): void;
49
+ }