@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.
- package/lib/index.cjs +3789 -1192
- package/lib/index.js +3783 -1193
- package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
- package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
- package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
- package/lib/src/generated/api/Events.d.ts +13 -3
- package/lib/src/generated/api/Events.js +1 -0
- package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
- package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
- package/lib/src/generated/api/FlowStateEntry.js +2 -0
- package/lib/src/generated/api/IceServer.d.ts +18 -0
- package/lib/src/generated/api/IceServer.js +2 -0
- package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
- package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
- package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
- package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
- package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
- package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
- package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
- package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
- package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
- package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
- package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
- package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
- package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
- package/lib/src/generated/api/PerspectiveResynced.js +2 -0
- package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
- package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
- package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
- package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
- package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
- package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
- package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
- package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
- package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
- package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
- package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
- package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
- package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
- package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
- package/lib/src/generated/api/RpcMethods.d.ts +134 -14
- package/lib/src/generated/api/RpcMethods.js +12 -0
- package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
- package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
- package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
- package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
- package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
- package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
- package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
- package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
- package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
- package/lib/src/generated/api/SfuCascadePipe.js +2 -0
- package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
- package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
- package/lib/src/generated/api/SfuConfig.d.ts +52 -0
- package/lib/src/generated/api/SfuConfig.js +1 -0
- package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
- package/lib/src/generated/api/SfuDataMessage.js +2 -0
- package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
- package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
- package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
- package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
- package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
- package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
- package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
- package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
- package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
- package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
- package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
- package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
- package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
- package/lib/src/generated/api/SfuRoomInfo.js +1 -0
- package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
- package/lib/src/generated/api/SfuRoomParams.js +2 -0
- package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
- package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
- package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
- package/lib/src/generated/api/SfuRoomRoster.js +2 -0
- package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
- package/lib/src/generated/api/SfuSendDataParams.js +2 -0
- package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
- package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
- package/lib/src/generated/api/SfuStatus.d.ts +24 -0
- package/lib/src/generated/api/SfuStatus.js +2 -0
- package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
- package/lib/src/generated/api/TrackMapEntry.js +2 -0
- package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
- package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
- package/lib/src/generated/api/index.d.ts +3 -0
- package/lib/src/index.d.ts +7 -0
- package/lib/src/index.js +4 -0
- package/lib/src/model/Ad4mModel.d.ts +84 -0
- package/lib/src/model/Ad4mModel.js +234 -4
- package/lib/src/model/ModelQueryBuilder.d.ts +16 -35
- package/lib/src/model/ModelQueryBuilder.js +88 -270
- package/lib/src/model/decorators.d.ts +32 -0
- package/lib/src/model/decorators.js +40 -1
- package/lib/src/model/shacl-gen.d.ts +3 -1
- package/lib/src/model/shacl-gen.js +13 -1
- package/lib/src/model/types.d.ts +7 -0
- package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
- package/lib/src/neighbourhood/MeshManager.js +1144 -0
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
- package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
- package/lib/src/neighbourhood/Session.d.ts +105 -0
- package/lib/src/neighbourhood/Session.js +412 -0
- package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
- package/lib/src/neighbourhood/SfuManager.js +619 -0
- package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
- package/lib/src/neighbourhood/SfuTypes.js +8 -0
- package/lib/src/perspectives/FlowInstance.d.ts +63 -24
- package/lib/src/perspectives/FlowInstance.js +74 -31
- package/lib/src/perspectives/FlowModels.d.ts +0 -16
- package/lib/src/perspectives/FlowModels.js +8 -16
- package/lib/src/perspectives/LiveQuery.d.ts +49 -0
- package/lib/src/perspectives/LiveQuery.js +169 -0
- package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
- package/lib/src/perspectives/PerspectiveClient.js +33 -36
- package/lib/src/perspectives/PerspectiveProxy.d.ts +67 -167
- package/lib/src/perspectives/PerspectiveProxy.js +121 -475
- package/lib/src/perspectives/TextContent.d.ts +31 -0
- package/lib/src/perspectives/TextContent.js +52 -0
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -0
- package/lib/src/perspectives/WakerSubscriptionManager.js +58 -17
- package/lib/src/shacl/SHACLFlow.d.ts +7 -4
- package/lib/src/shacl/SHACLFlow.js +7 -4
- package/lib/src/shacl/SHACLShape.d.ts +9 -0
- package/lib/src/shacl/SHACLShape.js +37 -0
- package/package.json +2 -2
- package/pnpm-workspace.yaml +4 -1
- package/src/Ad4mClient.test.ts +89 -17
- package/src/generated/api/AgentsByDidsRequest.ts +3 -0
- package/src/generated/api/CallSessionInfo.ts +20 -0
- package/src/generated/api/DiscardBatchRequest.ts +3 -0
- package/src/generated/api/Events.ts +14 -3
- package/src/generated/api/FlowStateChangedEvent.ts +36 -0
- package/src/generated/api/FlowStateEntry.ts +18 -0
- package/src/generated/api/IceServer.ts +19 -0
- package/src/generated/api/OnlineAgent.ts +6 -1
- package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
- package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
- package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
- package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
- package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
- package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
- package/src/generated/api/PerspectiveResynced.ts +7 -0
- package/src/generated/api/PerspectiveSubscribed.ts +8 -0
- package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
- package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
- package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
- package/src/generated/api/QueryUpdatesLagged.ts +7 -0
- package/src/generated/api/RemoveSubjectRequest.ts +7 -0
- package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
- package/src/generated/api/RpcMethods.ts +68 -8
- package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
- package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
- package/src/generated/api/SfuCallJoinParams.ts +13 -0
- package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
- package/src/generated/api/SfuCascadePipe.ts +3 -0
- package/src/generated/api/SfuCascadeStatus.ts +7 -0
- package/src/generated/api/SfuConfig.ts +53 -0
- package/src/generated/api/SfuDataMessage.ts +23 -0
- package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
- package/src/generated/api/SfuMigrateEvent.ts +20 -0
- package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
- package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
- package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
- package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
- package/src/generated/api/SfuRoomInfo.ts +7 -0
- package/src/generated/api/SfuRoomParams.ts +3 -0
- package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
- package/src/generated/api/SfuRoomRoster.ts +12 -0
- package/src/generated/api/SfuSendDataParams.ts +7 -0
- package/src/generated/api/SfuSetConfigParams.ts +4 -0
- package/src/generated/api/SfuStatus.ts +24 -0
- package/src/generated/api/TrackMapEntry.ts +18 -0
- package/src/generated/api/UpdateSubjectRequest.ts +10 -0
- package/src/generated/api/index.ts +3 -0
- package/src/index.ts +7 -0
- package/src/model/Ad4mModel.test.ts +255 -231
- package/src/model/Ad4mModel.ts +271 -4
- package/src/model/ModelQueryBuilder.ts +103 -310
- package/src/model/abstract-classes.test.ts +225 -0
- package/src/model/decorators.ts +81 -0
- package/src/model/shacl-gen.ts +13 -0
- package/src/model/types.ts +7 -0
- package/src/neighbourhood/MeshManager.test.ts +2640 -0
- package/src/neighbourhood/MeshManager.ts +1350 -0
- package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
- package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
- package/src/neighbourhood/Session.test.ts +800 -0
- package/src/neighbourhood/Session.ts +525 -0
- package/src/neighbourhood/SfuManager.test.ts +677 -0
- package/src/neighbourhood/SfuManager.ts +803 -0
- package/src/neighbourhood/SfuTypes.ts +40 -0
- package/src/perspectives/FlowInstance.ts +108 -31
- package/src/perspectives/FlowModels.ts +8 -18
- package/src/perspectives/LiveQuery.test.ts +197 -0
- package/src/perspectives/LiveQuery.ts +189 -0
- package/src/perspectives/PerspectiveClient.ts +51 -51
- package/src/perspectives/PerspectiveProxy.test.ts +85 -401
- package/src/perspectives/PerspectiveProxy.ts +126 -536
- package/src/perspectives/TextContent.test.ts +123 -0
- package/src/perspectives/TextContent.ts +36 -0
- package/src/perspectives/WakerSubscriptionManager.test.ts +88 -6
- package/src/perspectives/WakerSubscriptionManager.ts +69 -18
- package/src/shacl/SHACLFlow.ts +7 -4
- package/src/shacl/SHACLShape.test.ts +2 -1
- package/src/shacl/SHACLShape.ts +49 -0
- package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
- package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
- package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
- package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
- package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
- package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
- /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
- /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 `
|
|
10
|
-
*
|
|
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 `
|
|
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
|
|
45
|
-
* `
|
|
46
|
-
*
|
|
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 `
|
|
176
|
-
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
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
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
*
|
|
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
|
-
/**
|
|
296
|
-
|
|
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 `
|
|
10
|
-
*
|
|
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 `
|
|
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
|
|
45
|
-
* `
|
|
46
|
-
*
|
|
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 `
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
*
|
|
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
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
323
|
+
paired.push([record, shape]);
|
|
298
324
|
}
|
|
299
|
-
|
|
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
|
-
/**
|
|
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.
|
|
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
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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
|
+
}
|