@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.
Files changed (55) hide show
  1. package/lib/index.cjs +817 -65
  2. package/lib/index.js +814 -66
  3. package/lib/src/ai/AIClient.d.ts +13 -0
  4. package/lib/src/ai/AIClient.js +15 -0
  5. package/lib/src/ai/AITypes.d.ts +5 -0
  6. package/lib/src/index.js +2 -0
  7. package/lib/src/model/Ad4mModel.d.ts +6 -1
  8. package/lib/src/model/Ad4mModel.js +41 -6
  9. package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
  10. package/lib/src/model/ModelQueryBuilder.js +97 -6
  11. package/lib/src/model/query-common.d.ts +10 -1
  12. package/lib/src/model/query-common.js +16 -0
  13. package/lib/src/model/query-sparql.d.ts +11 -0
  14. package/lib/src/model/query-sparql.js +93 -1
  15. package/lib/src/model/query-utils.js +16 -0
  16. package/lib/src/model/shacl-gen.js +12 -0
  17. package/lib/src/model/types.d.ts +320 -3
  18. package/lib/src/model/types.js +9 -0
  19. package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
  20. package/lib/src/perspectives/FlowInstance.d.ts +176 -12
  21. package/lib/src/perspectives/FlowInstance.js +77 -13
  22. package/lib/src/perspectives/FlowModels.d.ts +40 -9
  23. package/lib/src/perspectives/FlowModels.js +59 -13
  24. package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
  25. package/lib/src/perspectives/PerspectiveClient.js +30 -0
  26. package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
  27. package/lib/src/perspectives/PerspectiveProxy.js +157 -7
  28. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
  29. package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
  30. package/lib/src/shacl/SHACLFlow.d.ts +43 -0
  31. package/package.json +1 -1
  32. package/src/ai/AIClient.ts +16 -0
  33. package/src/ai/AITypes.ts +5 -0
  34. package/src/index.ts +2 -0
  35. package/src/model/Ad4mModel.test.ts +442 -0
  36. package/src/model/Ad4mModel.ts +39 -7
  37. package/src/model/ModelQueryBuilder.ts +101 -10
  38. package/src/model/query-common.ts +20 -1
  39. package/src/model/query-sparql.test.ts +115 -0
  40. package/src/model/query-sparql.ts +97 -1
  41. package/src/model/query-utils.ts +18 -0
  42. package/src/model/relation-filtering.test.ts +7 -0
  43. package/src/model/shacl-gen.ts +12 -0
  44. package/src/model/shacl-roundtrip.test.ts +71 -0
  45. package/src/model/types-typed-query.test.ts +42 -0
  46. package/src/model/types.ts +316 -6
  47. package/src/perspectives/AutoProcessor.ts +8 -0
  48. package/src/perspectives/FlowInstance.ts +194 -13
  49. package/src/perspectives/FlowModels.ts +53 -13
  50. package/src/perspectives/PerspectiveClient.ts +62 -0
  51. package/src/perspectives/PerspectiveProxy.test.ts +272 -0
  52. package/src/perspectives/PerspectiveProxy.ts +163 -7
  53. package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
  54. package/src/perspectives/WakerSubscriptionManager.ts +197 -9
  55. 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 vs. what's coming in §7 / slice 10.6
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
- * Mutations + subscriptions (`proposeTransition`, `accept`, `reject`,
32
- * `fireAction`, `onStateChange`, `onProposalAdded`, `onProposalResolved`)
33
- * land with the consensus-engine slice (§4.3 / slice 10.6). Rather than
34
- * ship them as `throw new Error("not yet")` stubs — which is a type-level
35
- * lie the caller only discovers at runtime — they are simply absent from
36
- * this class until the engine is wired.
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. The consensus
112
- * engine (slice 10.6) will read the record's `currentState` when it
113
- * fires transitions.
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 (this.record as any).baseExpression as string;
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
- * Note: the consensus engine (slice 10.6) will start writing these; today
362
- * they only exist when a client wrote one directly (or a test seeded one).
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
- * engine does not yet mint these — that lands with the consensus firing
14
- * work in a later PR arc. This class defines the on-graph shape so:
15
- * - clients can build UI over proposals immediately (Deliberation demo);
16
- * - the SDNA-parity test locks TS/Rust drift the moment the JSON exists
17
- * (`rust-executor/src/perspectives/hardwired_sdna/flow_transition_proposal.json`);
18
- * - the engine can start writing into this shape when consensus lands
19
- * without touching the client-side surface.
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/<uuid>` when the engine mints it, but the class
30
- // carries no URI-format constraint — apps constructing proposals directly may
31
- // choose any URI they can defend as unique.
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
- /** Name of the state the flow is currently in. */
151
- @Property({ through: "ad4m://flow/current_state", required: true })
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/… →