@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-flows-1
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 +817 -65
- package/lib/index.js +814 -66
- package/lib/src/ai/AIClient.d.ts +13 -0
- package/lib/src/ai/AIClient.js +15 -0
- package/lib/src/ai/AITypes.d.ts +5 -0
- package/lib/src/index.js +2 -0
- package/lib/src/model/Ad4mModel.d.ts +6 -1
- package/lib/src/model/Ad4mModel.js +41 -6
- package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
- package/lib/src/model/ModelQueryBuilder.js +97 -6
- package/lib/src/model/query-common.d.ts +10 -1
- package/lib/src/model/query-common.js +16 -0
- package/lib/src/model/query-sparql.d.ts +11 -0
- package/lib/src/model/query-sparql.js +93 -1
- package/lib/src/model/query-utils.js +16 -0
- package/lib/src/model/shacl-gen.js +12 -0
- package/lib/src/model/types.d.ts +320 -3
- package/lib/src/model/types.js +9 -0
- package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
- package/lib/src/perspectives/FlowInstance.d.ts +176 -12
- package/lib/src/perspectives/FlowInstance.js +77 -13
- package/lib/src/perspectives/FlowModels.d.ts +40 -9
- package/lib/src/perspectives/FlowModels.js +59 -13
- package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
- package/lib/src/perspectives/PerspectiveClient.js +30 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
- package/lib/src/perspectives/PerspectiveProxy.js +157 -7
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
- package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
- package/lib/src/shacl/SHACLFlow.d.ts +43 -0
- package/package.json +1 -1
- package/src/ai/AIClient.ts +16 -0
- package/src/ai/AITypes.ts +5 -0
- package/src/index.ts +2 -0
- package/src/model/Ad4mModel.test.ts +442 -0
- package/src/model/Ad4mModel.ts +39 -7
- package/src/model/ModelQueryBuilder.ts +101 -10
- package/src/model/query-common.ts +20 -1
- package/src/model/query-sparql.test.ts +115 -0
- package/src/model/query-sparql.ts +97 -1
- package/src/model/query-utils.ts +18 -0
- package/src/model/relation-filtering.test.ts +7 -0
- package/src/model/shacl-gen.ts +12 -0
- package/src/model/shacl-roundtrip.test.ts +71 -0
- package/src/model/types-typed-query.test.ts +42 -0
- package/src/model/types.ts +316 -6
- package/src/perspectives/AutoProcessor.ts +8 -0
- package/src/perspectives/FlowInstance.ts +194 -13
- package/src/perspectives/FlowModels.ts +53 -13
- package/src/perspectives/PerspectiveClient.ts +62 -0
- package/src/perspectives/PerspectiveProxy.test.ts +272 -0
- package/src/perspectives/PerspectiveProxy.ts +163 -7
- package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
- package/src/perspectives/WakerSubscriptionManager.ts +197 -9
- package/src/shacl/SHACLFlow.ts +44 -0
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
* than the `wrap` escape hatch, which exists for tests that already own
|
|
18
18
|
* a matched (record, shape) pair.
|
|
19
19
|
*
|
|
20
|
-
* # What's here
|
|
20
|
+
* # What's here, and what is still absent
|
|
21
21
|
*
|
|
22
22
|
* Read surface (implemented today, PR #929):
|
|
23
23
|
* - `uri`, `subject`, `flowName`, `currentStateName`, `startedAtMillis`
|
|
@@ -28,12 +28,31 @@
|
|
|
28
28
|
* - `proposals()` — queries `FlowTransitionProposal` records that
|
|
29
29
|
* target this instance's URI.
|
|
30
30
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
31
|
+
* - `acceptProposal()` / `rejectProposal()` — the consensus write API:
|
|
32
|
+
* accept counts your DID toward the flow's consensusRule and fires the
|
|
33
|
+
* transition at quorum; reject withdraws only the links you signed and
|
|
34
|
+
* resolves to how many went. Reject is not a cancel — another agent's
|
|
35
|
+
* proposal is theirs, and because state is recomputed from the links
|
|
36
|
+
* present now, withdrawing a vote that had settled an edge moves the
|
|
37
|
+
* flow back to where it stood before it.
|
|
38
|
+
*
|
|
39
|
+
* - `proposeTransition()` — the manual write path: propose an edge as this
|
|
40
|
+
* agent, or co-sign the equivalent proposal another agent already opened.
|
|
41
|
+
* Its `FlowProposeResult` is what tells queued from no-op from stalled.
|
|
42
|
+
*
|
|
43
|
+
* 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.
|
|
47
|
+
*
|
|
48
|
+
* ## The guard-free rule
|
|
49
|
+
*
|
|
50
|
+
* A state with no `requires` guard is **never** proposed by the engine, on
|
|
51
|
+
* any replica, ever — `flow_evaluator`'s auto-proposal composer skips it by
|
|
52
|
+
* design. Nothing in the graph implies a human started work; they said so.
|
|
53
|
+
* So states like "in progress" and "in review" only ever advance through
|
|
54
|
+
* `proposeTransition`. This is a permanent contract, not a gap: wire the
|
|
55
|
+
* button, or the instance sits there.
|
|
37
56
|
*/
|
|
38
57
|
|
|
39
58
|
import { PerspectiveProxy } from "./PerspectiveProxy";
|
|
@@ -41,6 +60,120 @@ import { Ad4mModel } from "../model/Ad4mModel";
|
|
|
41
60
|
import { FlowInstanceRecord, FlowTransitionProposal } from "./FlowModels";
|
|
42
61
|
import { SHACLFlow, FlowState, FlowTransition } from "../shacl/SHACLFlow";
|
|
43
62
|
|
|
63
|
+
/** One fired flow transition, as returned by {@link FlowInstance.acceptProposal}
|
|
64
|
+
* (and, engine-side, by every consensus pass). */
|
|
65
|
+
export interface FlowFireOutcome {
|
|
66
|
+
instanceUri: string;
|
|
67
|
+
fromState: string;
|
|
68
|
+
toState: string;
|
|
69
|
+
voters: string[];
|
|
70
|
+
contributingProposalUris: string[];
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** What one {@link FlowInstance.proposeTransition} call did, and where the
|
|
74
|
+
* flow stands after it.
|
|
75
|
+
*
|
|
76
|
+
* A bare `FlowFireOutcome[]` could not distinguish "queued, waiting for other
|
|
77
|
+
* voters" from "you had already voted on this" from "the instance is stalled":
|
|
78
|
+
* all three are the empty array, and all three want different UI.
|
|
79
|
+
*
|
|
80
|
+
* Read the result like this:
|
|
81
|
+
*
|
|
82
|
+
* | `outcomes` | `recordedVote` | `contested` | meaning |
|
|
83
|
+
* |---|---|---|---|
|
|
84
|
+
* | non-empty | — | — | the transition fired |
|
|
85
|
+
* | `[]` | `true` | `false` | your vote landed; waiting for other voters |
|
|
86
|
+
* | `[]` | `false` | `false` | you had already voted; nothing was written |
|
|
87
|
+
* | `[]` | — | `true` | the flow is stalled — do not show "awaiting votes" |
|
|
88
|
+
*/
|
|
89
|
+
/**
|
|
90
|
+
* One output of a run, named when proposing a transition into a terminal
|
|
91
|
+
* state: an instance, and the class it is an instance of. Every co-signer
|
|
92
|
+
* loads it through that class and hashes its content, so the proposal
|
|
93
|
+
* commits to the instance as it is now, not just to its id.
|
|
94
|
+
*/
|
|
95
|
+
export interface FlowOutputRef {
|
|
96
|
+
className: string;
|
|
97
|
+
id: string;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export interface FlowProposeResult {
|
|
101
|
+
/** The live proposal this call minted or joined — always the one for the
|
|
102
|
+
* edge, whether this call wrote it or found it open. Hand it to another
|
|
103
|
+
* agent's `acceptProposal`, offer `rejectProposal` on it, or render it as
|
|
104
|
+
* "pending — withdraw?". */
|
|
105
|
+
proposalUri: string;
|
|
106
|
+
/** `true` when this call wrote the proposal; `false` when an equivalent
|
|
107
|
+
* one was already open and this call joined it. */
|
|
108
|
+
minted: boolean;
|
|
109
|
+
/** `true` when this call recorded a vote for the calling agent — its own
|
|
110
|
+
* vote on a mint, an `acceptedBy` on a join. `false` means the agent had
|
|
111
|
+
* already voted and nothing was written. */
|
|
112
|
+
recordedVote: boolean;
|
|
113
|
+
/** Consensus events this call recorded for the first time. Empty while
|
|
114
|
+
* the edge is short of quorum. */
|
|
115
|
+
outcomes: FlowFireOutcome[];
|
|
116
|
+
/** The instance's derived state after the call. */
|
|
117
|
+
derivedState: string;
|
|
118
|
+
/** `true` when two edges out of `derivedState` both carry quorum: the flow
|
|
119
|
+
* is irreversibly stalled and must not be shown as "awaiting votes". */
|
|
120
|
+
contested: boolean;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* One instance a verified flow receipt speaks for — an entry of
|
|
125
|
+
* `PerspectiveProxy.flowValidOutputs(flow, state?)`.
|
|
126
|
+
*
|
|
127
|
+
* Every entry has already passed the whole verification chain executor-side:
|
|
128
|
+
* the receipt's signatures and quorum re-checked, its outputs bound to the
|
|
129
|
+
* quorum-signed commitment (#1104), and the instance's *live* content still
|
|
130
|
+
* equal to what the quorum committed to. An output edited since the run
|
|
131
|
+
* completed is not listed, although the receipt itself stays verifiable.
|
|
132
|
+
*/
|
|
133
|
+
export interface FlowValidOutput {
|
|
134
|
+
/** The instance, as the `(className, id)` pair the quorum committed to. */
|
|
135
|
+
output: FlowOutputRef;
|
|
136
|
+
/** The instance's content as committed at completion (its `modelQuery`
|
|
137
|
+
* hydration, JSON-encoded). */
|
|
138
|
+
content: string;
|
|
139
|
+
/** The terminal state the granting run settled into, re-derived by the
|
|
140
|
+
* verifier. */
|
|
141
|
+
terminalState: string;
|
|
142
|
+
/** Content-derived URI of the receipt that proves this output. */
|
|
143
|
+
receiptUri: string;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* What `PerspectiveProxy.verifyFlowReceipt` learned — a THREE-way answer,
|
|
148
|
+
* not a boolean, and collapsing it to one is the classic mistake:
|
|
149
|
+
*
|
|
150
|
+
* - `"verified"` — the carried material re-derives the claim;
|
|
151
|
+
* - `"rejected"` — the material was checked and does not hold up;
|
|
152
|
+
* - `"undecidable"`— this replica cannot decide (it lacks the flow
|
|
153
|
+
* definition, or holds a different one). Refuse to act on it exactly as
|
|
154
|
+
* on `"rejected"`, but do NOT treat it as evidence against the receipt
|
|
155
|
+
* or its minter — sync the definition and ask again.
|
|
156
|
+
*/
|
|
157
|
+
export interface FlowReceiptVerdict {
|
|
158
|
+
outcome: "verified" | "rejected" | "undecidable";
|
|
159
|
+
/** Human-readable reason, phrased for the outcome it accompanies. */
|
|
160
|
+
detail: string;
|
|
161
|
+
/** Only on `"verified"`: the terminal state the reader's own fold reached. */
|
|
162
|
+
terminalState?: string;
|
|
163
|
+
/** Only on `"verified"`: the outputs the receipt speaks for. */
|
|
164
|
+
outputs?: FlowOutputRef[];
|
|
165
|
+
/** Only on `"verified"`: the distinct eligible DIDs that made the quorum. */
|
|
166
|
+
voters?: string[];
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** What `PerspectiveProxy.mintFlowReceipt` wrote: the receipt's
|
|
170
|
+
* content-derived node URI and its body (opaque to clients — verify it with
|
|
171
|
+
* `verifyFlowReceipt`, never by inspection). */
|
|
172
|
+
export interface FlowMintedReceipt {
|
|
173
|
+
receiptUri: string;
|
|
174
|
+
receipt: object;
|
|
175
|
+
}
|
|
176
|
+
|
|
44
177
|
/**
|
|
45
178
|
* Extract the flow's human-readable name from its canonical URI.
|
|
46
179
|
*
|
|
@@ -108,9 +241,15 @@ export class FlowInstance {
|
|
|
108
241
|
*
|
|
109
242
|
* The returned wrapper carries the parsed `SHACLFlow` alongside the
|
|
110
243
|
* on-graph record, so `currentState` / `availableTransitions` /
|
|
111
|
-
* `proposals` accessors work without further round-trips.
|
|
112
|
-
*
|
|
113
|
-
*
|
|
244
|
+
* `proposals` accessors work without further round-trips.
|
|
245
|
+
*
|
|
246
|
+
* The record's `currentState` is a per-replica cache the consensus engine
|
|
247
|
+
* writes as a local link. It is read back only for display — the cache-first
|
|
248
|
+
* path in `gather_active_flow_contexts` fills the state rendered into LLM
|
|
249
|
+
* context — and **never as authority**: anything that decides something
|
|
250
|
+
* (the fold, the mint pass) derives state from the signed links present now
|
|
251
|
+
* and does not consult the cache. Treat it as a display hint, not as the
|
|
252
|
+
* flow's state.
|
|
114
253
|
*
|
|
115
254
|
* @param perspective - The perspective the flow instance lives on
|
|
116
255
|
* @param flowName - Name of a `SHACLFlow` already registered on the perspective
|
|
@@ -283,7 +422,7 @@ export class FlowInstance {
|
|
|
283
422
|
* `FlowTransitionProposal.flowInstance` references).
|
|
284
423
|
*/
|
|
285
424
|
get uri(): string {
|
|
286
|
-
return
|
|
425
|
+
return this.record.id;
|
|
287
426
|
}
|
|
288
427
|
|
|
289
428
|
/**
|
|
@@ -358,12 +497,54 @@ export class FlowInstance {
|
|
|
358
497
|
* for the where-filter — one SPARQL round-trip, no client-side
|
|
359
498
|
* filtering.
|
|
360
499
|
*
|
|
361
|
-
*
|
|
362
|
-
*
|
|
500
|
+
* These are written by the executor's consensus pass when it mints a
|
|
501
|
+
* transition, and by clients proposing directly. Superseded proposals are
|
|
502
|
+
* not swept here — a stale one is simply never counted by the fold, and
|
|
503
|
+
* accepting it fails with a stale-state error.
|
|
363
504
|
*/
|
|
364
505
|
async proposals(): Promise<FlowTransitionProposal[]> {
|
|
365
506
|
return FlowTransitionProposal.findAll(this.perspective, {
|
|
366
507
|
where: { flowInstance: this.uri },
|
|
367
508
|
});
|
|
368
509
|
}
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* Propose a flow transition for this instance, as the calling agent.
|
|
513
|
+
*
|
|
514
|
+
* The executor evaluates the guard on its own replica, seals the evidence,
|
|
515
|
+
* and either writes a new proposal or — when an equivalent one is already
|
|
516
|
+
* open, i.e. another agent pressed the same button first — co-signs that
|
|
517
|
+
* one. When the resulting vote reaches the target state's
|
|
518
|
+
* `consensusRule.n`, the transition fires in the same call.
|
|
519
|
+
*
|
|
520
|
+
* How to read the result — fired vs. queued vs. no-op vs. stalled — is
|
|
521
|
+
* documented on {@link FlowProposeResult} itself.
|
|
522
|
+
*
|
|
523
|
+
* `outputs` names the instances the run produces, as `{ className, id }`
|
|
524
|
+
* pairs, for a transition into a terminal state. The proposal signs a hash
|
|
525
|
+
* over their content, every co-signer recomputes it on its own replica,
|
|
526
|
+
* and a receipt for the run speaks for exactly these instances as they
|
|
527
|
+
* stood at completion.
|
|
528
|
+
*
|
|
529
|
+
* Throws when `toState` is not reachable from the derived state, when the
|
|
530
|
+
* target state carries a `requires` guard that is not currently satisfied
|
|
531
|
+
* on this replica, when the instance is already contested, when `outputs`
|
|
532
|
+
* is given for a non-terminal state or names something that is not an
|
|
533
|
+
* instance of its class, or
|
|
534
|
+
* when an open proposal on the same edge names different outputs.
|
|
535
|
+
*/
|
|
536
|
+
async proposeTransition(toState: string, rationale?: string, outputs?: FlowOutputRef[]): Promise<FlowProposeResult> {
|
|
537
|
+
return this.perspective.proposeFlowTransition(this.uri, toState, rationale, outputs);
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
async acceptProposal(proposal: FlowTransitionProposal | string): Promise<FlowFireOutcome[]> {
|
|
541
|
+
const uri = typeof proposal === "string" ? proposal : proposal.id;
|
|
542
|
+
return this.perspective.acceptFlowProposal(uri);
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/** Withdraw our own links from a proposal; resolves to how many went. */
|
|
546
|
+
async rejectProposal(proposal: FlowTransitionProposal | string): Promise<number> {
|
|
547
|
+
const uri = typeof proposal === "string" ? proposal : proposal.id;
|
|
548
|
+
return this.perspective.rejectFlowProposal(uri);
|
|
549
|
+
}
|
|
369
550
|
}
|
|
@@ -9,14 +9,14 @@
|
|
|
9
9
|
* Querying:
|
|
10
10
|
* const pending = await FlowTransitionProposal.findAll(perspective);
|
|
11
11
|
*
|
|
12
|
-
* Slice 5/7 of the flow-implementation arc (design doc §4.2). The Rust
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* - the
|
|
19
|
-
*
|
|
12
|
+
* Slice 5/7 of the flow-implementation arc (design doc §4.2). The Rust engine
|
|
13
|
+
* mints these as of #987 — see `flow_classes.rs` (`mint_proposal`, URIs at
|
|
14
|
+
* `ad4m://flow/proposal/{id}`) — and reads them back in
|
|
15
|
+
* `flow_instance/atom.rs`. A UI mints or joins them through
|
|
16
|
+
* `FlowInstance.proposeTransition`. This class is the client-side mirror:
|
|
17
|
+
* - clients build UI over proposals without knowing the raw link predicates;
|
|
18
|
+
* - the SDNA-parity test locks TS/Rust drift against
|
|
19
|
+
* `rust-executor/src/perspectives/hardwired_sdna/flow_transition_proposal.json`.
|
|
20
20
|
*/
|
|
21
21
|
|
|
22
22
|
import { Ad4mModel } from "../model/Ad4mModel";
|
|
@@ -26,9 +26,12 @@ import { Model } from "../model/decorators";
|
|
|
26
26
|
// ── FlowTransitionProposal ──────────────────────────────────────────────────
|
|
27
27
|
// Mirrors the Rust hardwired `flow_transition_proposal.json` SDNA (once wired
|
|
28
28
|
// on the engine side; see file header). One node per proposed transition; the
|
|
29
|
-
// URI is `ad4m://flow/proposal/<
|
|
30
|
-
//
|
|
31
|
-
//
|
|
29
|
+
// URI the engine mints is `ad4m://flow/proposal/<hash>` — the content address
|
|
30
|
+
// of the proposer-signed fields under the `nonce` (#1108). The class carries
|
|
31
|
+
// no URI-format constraint, but a proposal whose URI is not that content
|
|
32
|
+
// address (including any app-chosen URI) is not engine-visible: co-signatures
|
|
33
|
+
// name the URI, so the engine only counts proposals whose URI commits to
|
|
34
|
+
// their fields.
|
|
32
35
|
|
|
33
36
|
@Model({ name: "FlowTransitionProposal" })
|
|
34
37
|
export class FlowTransitionProposal extends Ad4mModel {
|
|
@@ -73,6 +76,37 @@ export class FlowTransitionProposal extends Ad4mModel {
|
|
|
73
76
|
@Property({ through: "ad4m://flow/evidence_hashes", required: true })
|
|
74
77
|
evidenceHashes: string = "";
|
|
75
78
|
|
|
79
|
+
/**
|
|
80
|
+
* The instances the proposer names as the run's outputs. Written only on
|
|
81
|
+
* a proposal into a terminal state; one link per output, ordering not
|
|
82
|
+
* significant. Each entry is the canonical JSON text of a
|
|
83
|
+
* `{ className, id }` pair (`FlowOutputRef`); `JSON.parse` it to read one.
|
|
84
|
+
*/
|
|
85
|
+
@HasMany({ through: "ad4m://flow/output", datatype: "xsd:string" })
|
|
86
|
+
outputs: string[] = [];
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* SHA-256 (hex) over the named outputs' content (each instance as
|
|
90
|
+
* `model_query` returns it through its class), signed by the proposer
|
|
91
|
+
* next to the evidence seal. Co-signers load the outputs and recompute it
|
|
92
|
+
* before voting, and a flow receipt's output preimages must hash to it.
|
|
93
|
+
* Empty on a proposal into a non-terminal state.
|
|
94
|
+
*/
|
|
95
|
+
@Property({ through: "ad4m://flow/outputs_hash" })
|
|
96
|
+
outputsHash: string = "";
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The proposer's uniqueness salt for this proposal's content-addressed
|
|
100
|
+
* URI (`ad4m://flow/proposal/<hash>`; the hash covers the instance, the
|
|
101
|
+
* edge, the seal, the outputs commitment, the proposer DID and this
|
|
102
|
+
* nonce). The engine writes a UUID. A proposal without one — or whose URI
|
|
103
|
+
* does not match its own signed fields — is not engine-visible:
|
|
104
|
+
* co-signatures name the URI, so the URI must commit to what they sign
|
|
105
|
+
* (#1108).
|
|
106
|
+
*/
|
|
107
|
+
@Property({ through: "ad4m://flow/nonce" })
|
|
108
|
+
nonce: string = "";
|
|
109
|
+
|
|
76
110
|
/**
|
|
77
111
|
* URI of the `InterpretationRun` node that produced this proposal, when
|
|
78
112
|
* the proposal came from an LLM extraction pass. Absent when a human
|
|
@@ -147,8 +181,14 @@ export class FlowInstanceRecord extends Ad4mModel {
|
|
|
147
181
|
@Property({ through: "ad4m://flow/base", required: true })
|
|
148
182
|
subject: string = "";
|
|
149
183
|
|
|
150
|
-
/**
|
|
151
|
-
|
|
184
|
+
/**
|
|
185
|
+
* The state name this replica's executor last derived for the flow — a
|
|
186
|
+
* per-replica cache written as a `local` link, never the authority (the
|
|
187
|
+
* fold over the signed proposals is). Optional on the shape: a row that
|
|
188
|
+
* synced in from a peer carries no value until the local consensus pass
|
|
189
|
+
* has run, so an empty string means "not yet derived here".
|
|
190
|
+
*/
|
|
191
|
+
@Property({ through: "ad4m://flow/current_state", local: true })
|
|
152
192
|
currentState: string = "";
|
|
153
193
|
|
|
154
194
|
// "When was this flow started?" is answered by `Ad4mModel`'s built-in
|
|
@@ -12,6 +12,14 @@ import { AIClient } from "../ai/AIClient";
|
|
|
12
12
|
import { AllInstancesResult } from "../model/types";
|
|
13
13
|
import type { TranscriptTurn } from "../generated/api";
|
|
14
14
|
import type { AddAutoProcessorConfig, AutoProcessorEvent, AutoProcessorNeighbourhoodStateEvent, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
|
|
15
|
+
// FlowInstance.ts owns the flow-proposal result types so they sit next to the
|
|
16
|
+
// `proposeTransition()` API they describe. `import type` keeps this out of the
|
|
17
|
+
// runtime module graph (FlowInstance → PerspectiveProxy → PerspectiveClient
|
|
18
|
+
// would otherwise be a cycle).
|
|
19
|
+
import type {
|
|
20
|
+
FlowFireOutcome, FlowMintedReceipt, FlowOutputRef, FlowProposeResult,
|
|
21
|
+
FlowReceiptVerdict, FlowValidOutput,
|
|
22
|
+
} from "./FlowInstance";
|
|
15
23
|
|
|
16
24
|
export type PerspectiveHandleCallback = (perspective: PerspectiveHandle) => null
|
|
17
25
|
export type UuidCallback = (uuid: string) => null
|
|
@@ -395,6 +403,60 @@ export class PerspectiveClient {
|
|
|
395
403
|
)
|
|
396
404
|
}
|
|
397
405
|
|
|
406
|
+
async proposeFlowTransition(
|
|
407
|
+
uuid: string,
|
|
408
|
+
instanceUri: string,
|
|
409
|
+
toState: string,
|
|
410
|
+
rationale?: string,
|
|
411
|
+
outputs?: FlowOutputRef[],
|
|
412
|
+
): Promise<FlowProposeResult> {
|
|
413
|
+
return this.#apiClient.call<FlowProposeResult>(
|
|
414
|
+
'perspective.proposeFlowTransition', { uuid, instanceUri, toState, rationale, outputs },
|
|
415
|
+
)
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
async acceptFlowProposal(uuid: string, proposalUri: string): Promise<FlowFireOutcome[]> {
|
|
419
|
+
return this.#apiClient.call<FlowFireOutcome[]>(
|
|
420
|
+
'perspective.acceptFlowProposal', { uuid, proposalUri },
|
|
421
|
+
)
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
/**
|
|
425
|
+
* Withdraw this agent's own links from a proposal. Resolves to how many
|
|
426
|
+
* were retracted — one for a withdrawn vote, more when retracting a
|
|
427
|
+
* proposal this agent opened.
|
|
428
|
+
*/
|
|
429
|
+
async rejectFlowProposal(uuid: string, proposalUri: string): Promise<number> {
|
|
430
|
+
const result = await this.#apiClient.call<{ retractedLinks: number }>(
|
|
431
|
+
'perspective.rejectFlowProposal', { uuid, proposalUri },
|
|
432
|
+
)
|
|
433
|
+
return result.retractedLinks
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/** Re-decide a flow receipt under this perspective's own flow catalogue. */
|
|
437
|
+
async verifyFlowReceipt(uuid: string, receipt: object): Promise<FlowReceiptVerdict> {
|
|
438
|
+
return this.#apiClient.call<FlowReceiptVerdict>(
|
|
439
|
+
'perspective.verifyFlowReceipt', { uuid, receipt },
|
|
440
|
+
)
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/** The instances that are, as they stand, valid outputs of `flow`
|
|
444
|
+
* (optionally: of runs settled into terminal state `state`). */
|
|
445
|
+
async flowValidOutputs(uuid: string, flow: string, state?: string): Promise<FlowValidOutput[]> {
|
|
446
|
+
return this.#apiClient.call<FlowValidOutput[]>(
|
|
447
|
+
'perspective.flowValidOutputs', { uuid, flow, state },
|
|
448
|
+
)
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/** Mint and store the receipt for a completed flow run. Fails while the
|
|
452
|
+
* run has not settled into a terminal state, and when an output's
|
|
453
|
+
* content no longer matches what the quorum committed to. */
|
|
454
|
+
async mintFlowReceipt(uuid: string, instanceUri: string): Promise<FlowMintedReceipt> {
|
|
455
|
+
return this.#apiClient.call<FlowMintedReceipt>(
|
|
456
|
+
'perspective.mintFlowReceipt', { uuid, instanceUri },
|
|
457
|
+
)
|
|
458
|
+
}
|
|
459
|
+
|
|
398
460
|
/**
|
|
399
461
|
* Subscribe to auto-processor step signals. `cb` fires for every
|
|
400
462
|
* `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
|