@coasys/ad4m 0.13.1-staging.13 → 0.13.1-staging.14

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 (64) hide show
  1. package/lib/index.cjs +548 -477
  2. package/lib/index.js +548 -473
  3. package/lib/src/agent/AgentClient.d.ts +9 -8
  4. package/lib/src/agent/AgentClient.js +46 -67
  5. package/lib/src/cache/KeyedCache.d.ts +51 -0
  6. package/lib/src/cache/KeyedCache.js +142 -0
  7. package/lib/src/expression/ExpressionClient.d.ts +14 -3
  8. package/lib/src/expression/ExpressionClient.js +49 -111
  9. package/lib/src/generated/api/ExpressionLookupError.d.ts +7 -0
  10. package/lib/src/generated/api/ExpressionLookupError.js +2 -0
  11. package/lib/src/generated/api/ExpressionManyEntry.d.ts +6 -0
  12. package/lib/src/generated/api/ExpressionManyEntry.js +1 -0
  13. package/lib/src/generated/api/FlowFiredEntry.d.ts +11 -0
  14. package/lib/src/generated/api/FlowFiredEntry.js +2 -0
  15. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +3 -3
  16. package/lib/src/generated/api/RpcMethods.d.ts +4 -2
  17. package/lib/src/model/Ad4mModel.d.ts +26 -2
  18. package/lib/src/model/Ad4mModel.js +125 -82
  19. package/lib/src/model/ModelQueryBuilder.d.ts +3 -0
  20. package/lib/src/model/ModelQueryBuilder.js +42 -14
  21. package/lib/src/model/index.d.ts +0 -1
  22. package/lib/src/model/index.js +0 -1
  23. package/lib/src/model/query-common.d.ts +8 -0
  24. package/lib/src/model/query-common.js +12 -0
  25. package/lib/src/model/types.d.ts +12 -3
  26. package/lib/src/perspectives/FlowModels.js +1 -1
  27. package/lib/src/perspectives/LiveQuery.d.ts +1 -1
  28. package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
  29. package/lib/src/perspectives/PerspectiveClient.js +83 -44
  30. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
  31. package/lib/src/perspectives/PerspectiveProxy.js +31 -69
  32. package/package.json +2 -2
  33. package/src/Ad4mClient.test.ts +17 -6
  34. package/src/agent/AgentClient.ts +46 -74
  35. package/src/cache/KeyedCache.test.ts +162 -0
  36. package/src/cache/KeyedCache.ts +179 -0
  37. package/src/cache/cache.test.ts +294 -71
  38. package/src/expression/ExpressionClient.ts +46 -131
  39. package/src/generated/api/ExpressionLookupError.ts +6 -0
  40. package/src/generated/api/ExpressionManyEntry.ts +8 -0
  41. package/src/generated/api/FlowFiredEntry.ts +11 -0
  42. package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
  43. package/src/generated/api/RpcMethods.ts +4 -2
  44. package/src/model/Ad4mModel.test.ts +237 -43
  45. package/src/model/Ad4mModel.ts +132 -98
  46. package/src/model/ModelQueryBuilder.ts +41 -15
  47. package/src/model/count-result-type.test.ts +72 -0
  48. package/src/model/index.ts +0 -1
  49. package/src/model/query-common.ts +13 -0
  50. package/src/model/relation-filtering.test.ts +3 -5
  51. package/src/model/types.ts +9 -3
  52. package/src/model/write-round-trips.test.ts +30 -6
  53. package/src/perspectives/FlowModels.ts +1 -1
  54. package/src/perspectives/LiveQuery.ts +1 -1
  55. package/src/perspectives/PerspectiveClient.test.ts +287 -0
  56. package/src/perspectives/PerspectiveClient.ts +101 -66
  57. package/src/perspectives/PerspectiveProxy.test.ts +6 -14
  58. package/src/perspectives/PerspectiveProxy.ts +33 -67
  59. package/src/perspectives/TextContent.test.ts +0 -16
  60. package/src/perspectives/shacl-rpc.test.ts +1 -1
  61. package/lib/src/model/query-cache.d.ts +0 -30
  62. package/lib/src/model/query-cache.js +0 -66
  63. package/src/model/query-cache.test.ts +0 -54
  64. package/src/model/query-cache.ts +0 -79
@@ -279,7 +279,8 @@ export declare function isTraverseScope(scope: Scope): scope is TraverseScope;
279
279
  * // One level deep
280
280
  * { comments: true }
281
281
  *
282
- * // Sub-query: only the 5 most-recent comments
282
+ * // Sub-query: only the 5 most-recent comments of each parent
283
+ * // (`limit` and `offset` page every parent's relation on its own)
283
284
  * { comments: { order: { createdAt: 'DESC' }, limit: 5 } }
284
285
  *
285
286
  * // Nested eager-load
@@ -367,6 +368,7 @@ export type Query = {
367
368
  order?: Order;
368
369
  offset?: number;
369
370
  limit?: number;
371
+ /** Ask for `totalCount`. Without it the result has none and the executor runs no COUNT query. */
370
372
  count?: boolean;
371
373
  /**
372
374
  * When true, SPARQL property getters (@Property with `getter`) ARE evaluated
@@ -691,13 +693,20 @@ export type AllInstancesResult = {
691
693
  AllInstances: Ad4mModel[];
692
694
  TotalCount?: number;
693
695
  };
694
- export type ResultsWithTotalCount<T> = {
696
+ /** A model query's rows; `totalCount` is set when the query asked for it (`count: true`). */
697
+ export type Page<T> = {
695
698
  results: T[];
696
699
  totalCount?: number;
697
700
  };
701
+ /** The result of `findAllAndCount()`, which always asks for the count. */
702
+ export type ResultsWithTotalCount<T> = {
703
+ results: T[];
704
+ totalCount: number;
705
+ };
706
+ /** The result of `paginate()` and `paginateSubscribe()`, which always ask for the count. */
698
707
  export type PaginationResult<T> = {
699
708
  results: T[];
700
- totalCount?: number;
709
+ totalCount: number;
701
710
  pageSize: number;
702
711
  pageNumber: number;
703
712
  };
@@ -127,7 +127,7 @@ let FlowTransitionProposal = class FlowTransitionProposal extends Ad4mModel {
127
127
  this.acceptedBy = [];
128
128
  // Whether this proposal settled an edge is not on the record: the
129
129
  // executor keeps that per agent, outside the graph (#1424). Ask
130
- // `PerspectiveProxy.flowFired(instance)` for the proposals your replica
130
+ // `PerspectiveProxy.flowFired(instances)` for the proposals your replica
131
131
  // recorded as fired, or listen with `onFlowStateChanged`.
132
132
  // "When was this proposal written?" is answered by `Ad4mModel`'s built-in
133
133
  // `createdAt`, synthesized on hydration from the earliest link timestamp
@@ -8,7 +8,7 @@ export interface Subscribed {
8
8
  /**
9
9
  * A `query-subscription-update` event: the change from the previous revision.
10
10
  * Model results carry `ids` (the new order), `upsert` (new or changed
11
- * instances) and `totalCount`; query results carry `added` / `removed` rows;
11
+ * instances) and, when the query set `count: true`, `totalCount`; query results carry `added` / `removed` rows;
12
12
  * a result that could not be diffed comes whole as `result`.
13
13
  */
14
14
  export interface QueryUpdate {
@@ -14,6 +14,7 @@ import type { TranscriptTurn } from "../generated/api";
14
14
  import type { AgentMessage } from "../generated/api/AgentMessage";
15
15
  import type { AgentReply } from "../generated/api/AgentReply";
16
16
  import type { JsonValue } from "../generated/api/serde_json/JsonValue";
17
+ import type { FlowFiredEntry } from "../generated/api/FlowFiredEntry";
17
18
  import type { CollectionItemAdded, CollectionItemRemoved, InstanceAddToCollection, InstanceCreate, InstanceCreated, InstanceRemove, InstanceRemoveFromCollection, InstanceRemoved, InstanceUpdate, InstanceUpdated } from "../generated/api";
18
19
  import type { AddAutoProcessorConfig, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
19
20
  import type { FlowFireOutcome, FlowMintedReceipt, FlowOutputRef, FlowProposeResult, FlowReceiptVerdict, FlowStateEntry, FlowValidOutput } from "./FlowInstance";
@@ -30,6 +31,13 @@ export declare class PerspectiveClient {
30
31
  publishSnapshotByUUID(uuid: string): Promise<string | null>;
31
32
  queryLinks(uuid: string, query: LinkQuery, options?: CallOptions): Promise<LinkExpression[]>;
32
33
  queryProlog(uuid: string, query: string, options?: CallOptions): Promise<unknown>;
34
+ /**
35
+ * Concurrent identical calls (same perspective and query, no `options`)
36
+ * share one RPC. Each caller parses its own copy of the reply, and a call
37
+ * made after the shared one settled makes a new RPC. So does a call made
38
+ * after a write through this client settled: the shared RPC may have been
39
+ * answered before the write (see `#wrote`).
40
+ */
33
41
  querySparql<T = any>(uuid: string, query: string, options?: CallOptions): Promise<T>;
34
42
  /** Open a live SPARQL query. Updates arrive through {@link onQueryUpdate}. */
35
43
  /** `options.signal` cancels the call, and the executor stops computing the first result. */
@@ -146,9 +154,11 @@ export declare class PerspectiveClient {
146
154
  /** The calling agent's recorded state of each flow instance it has
147
155
  * derived, optionally narrowed to `instances`. */
148
156
  flowStates(uuid: string, instances?: string[]): Promise<FlowStateEntry[]>;
149
- /** The proposals of `instance` the calling agent's replica recorded as
150
- * fired, sorted. */
151
- flowFired(uuid: string, instance: string): Promise<string[]>;
157
+ /** For each of `instances`, in order, the proposals the calling agent's
158
+ * replica recorded as fired, sorted. One call covers up to 200
159
+ * instances (more is refused with a 400); split a longer list into
160
+ * batches of 200. */
161
+ flowFired(uuid: string, instances: string[]): Promise<FlowFiredEntry[]>;
152
162
  /** Mint and store the receipt for a completed flow run. Fails while the
153
163
  * run has not settled into a terminal state, and when an output's
154
164
  * content no longer matches what the quorum committed to. */
@@ -222,10 +232,11 @@ export declare class PerspectiveClient {
222
232
  }>;
223
233
  } | null>;
224
234
  /**
225
- * Retrieve all SHACL shapes in one call. Returns an array of
226
- * `{name, shapeUri, links}` — one entry per shape (one RPC call).
235
+ * Retrieve SHACL shapes in one call: every shape, or only those in
236
+ * `names` (unknown names are left out). Returns `{name, shapeUri, links}`
237
+ * per shape.
227
238
  */
228
- getAllShacl(uuid: string): Promise<Array<{
239
+ getAllShacl(uuid: string, names?: string[]): Promise<Array<{
229
240
  name: string;
230
241
  shapeUri: string;
231
242
  links: Array<{
@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _PerspectiveClient_instances, _PerspectiveClient_apiClient, _PerspectiveClient_expressionClient, _PerspectiveClient_neighbourhoodClient, _PerspectiveClient_aiClient, _PerspectiveClient_released;
12
+ var _PerspectiveClient_instances, _PerspectiveClient_apiClient, _PerspectiveClient_expressionClient, _PerspectiveClient_neighbourhoodClient, _PerspectiveClient_aiClient, _PerspectiveClient_sparqlInFlight, _PerspectiveClient_writeGeneration, _PerspectiveClient_wrote, _PerspectiveClient_released;
13
13
  import { ApiClient, RpcError } from '../apiClient';
14
14
  import { LinkExpression, LinkExpressionMutations, linkExpressionInputToWire, linkExpressionToWire, linkMutationsToWire, } from "../links/Links";
15
15
  import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
@@ -37,6 +37,11 @@ export class PerspectiveClient {
37
37
  _PerspectiveClient_expressionClient.set(this, void 0);
38
38
  _PerspectiveClient_neighbourhoodClient.set(this, void 0);
39
39
  _PerspectiveClient_aiClient.set(this, void 0);
40
+ _PerspectiveClient_sparqlInFlight.set(this, new Map()
41
+ /** Per perspective, how many writes through this client have settled; part of the in-flight key. */
42
+ );
43
+ /** Per perspective, how many writes through this client have settled; part of the in-flight key. */
44
+ _PerspectiveClient_writeGeneration.set(this, new Map());
40
45
  __classPrivateFieldSet(this, _PerspectiveClient_apiClient, sharedApiClient || new ApiClient(baseUrl, token), "f");
41
46
  }
42
47
  setExpressionClient(client) {
@@ -96,9 +101,24 @@ export class PerspectiveClient {
96
101
  const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.queryProlog', { uuid, query }, options);
97
102
  return JSON.parse(result);
98
103
  }
104
+ /**
105
+ * Concurrent identical calls (same perspective and query, no `options`)
106
+ * share one RPC. Each caller parses its own copy of the reply, and a call
107
+ * made after the shared one settled makes a new RPC. So does a call made
108
+ * after a write through this client settled: the shared RPC may have been
109
+ * answered before the write (see `#wrote`).
110
+ */
99
111
  async querySparql(uuid, query, options) {
100
- const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.querySparql', { uuid, engine: 'sparql', query }, options);
101
- return JSON.parse(result);
112
+ if (options)
113
+ return JSON.parse(await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.querySparql', { uuid, engine: 'sparql', query }, options));
114
+ const key = `${uuid}\n${__classPrivateFieldGet(this, _PerspectiveClient_writeGeneration, "f").get(uuid) ?? 0}\n${query}`;
115
+ let reply = __classPrivateFieldGet(this, _PerspectiveClient_sparqlInFlight, "f").get(key);
116
+ if (!reply) {
117
+ reply = __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.querySparql', { uuid, engine: 'sparql', query })
118
+ .finally(() => __classPrivateFieldGet(this, _PerspectiveClient_sparqlInFlight, "f").delete(key));
119
+ __classPrivateFieldGet(this, _PerspectiveClient_sparqlInFlight, "f").set(key, reply);
120
+ }
121
+ return JSON.parse(await reply);
102
122
  }
103
123
  /** Open a live SPARQL query. Updates arrive through {@link onQueryUpdate}. */
104
124
  /** `options.signal` cancels the call, and the executor stops computing the first result. */
@@ -155,19 +175,19 @@ export class PerspectiveClient {
155
175
  return { perspectiveRemove: result };
156
176
  }
157
177
  async addLink(uuid, link, status = 'shared', batchId) {
158
- const added = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLink', { uuid, link, status, batchId });
178
+ const added = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLink', { uuid, link, status, batchId }));
159
179
  return LinkExpression.fromWire(added);
160
180
  }
161
181
  async addLinks(uuid, links, status = 'shared', batchId) {
162
- const added = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLinks', { uuid, links, status, batchId });
182
+ const added = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLinks', { uuid, links, status, batchId }));
163
183
  return added.map(LinkExpression.fromWire);
164
184
  }
165
185
  async removeLinks(uuid, links, batchId) {
166
- const removed = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeLinks', { uuid, links: links.map(linkExpressionInputToWire), batchId });
186
+ const removed = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeLinks', { uuid, links: links.map(linkExpressionInputToWire), batchId }));
167
187
  return removed.map(LinkExpression.fromWire);
168
188
  }
169
189
  async linkMutations(uuid, mutations, status) {
170
- const diff = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.linkMutations', { uuid, mutations: linkMutationsToWire(mutations), status });
190
+ const diff = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.linkMutations', { uuid, mutations: linkMutationsToWire(mutations), status }));
171
191
  return LinkExpressionMutations.fromWire(diff);
172
192
  }
173
193
  /**
@@ -187,11 +207,11 @@ export class PerspectiveClient {
187
207
  * are NOT re-parented — same rule as the watcher).
188
208
  */
189
209
  async runInterpretation(uuid, transcript, basePrefix, classes, existingScope, mintScope, observe, options) {
190
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', {
210
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretation', {
191
211
  uuid, transcript, basePrefix, classes, existingScope, mintScope,
192
212
  observationId: observe?.observationId,
193
213
  emitDebugEvents: observe?.emitDebugEvents,
194
- }, options);
214
+ }, options));
195
215
  }
196
216
  /**
197
217
  * Tool-calling counterpart to {@link runInterpretation}. The LLM sees a
@@ -214,7 +234,7 @@ export class PerspectiveClient {
214
234
  // `emitDebugEvents` is a dead-letter without an observationId
215
235
  // (nothing to key against); the server gates on both.
216
236
  observationId, emitDebugEvents, options) {
217
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretationWithHarness', {
237
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runInterpretationWithHarness', {
218
238
  uuid,
219
239
  transcript,
220
240
  basePrefix,
@@ -224,7 +244,7 @@ export class PerspectiveClient {
224
244
  existingScope,
225
245
  observationId,
226
246
  emitDebugEvents,
227
- }, options);
247
+ }, options));
228
248
  }
229
249
  /**
230
250
  * A conversation with a model in this perspective, using the executor's own tools: the tools
@@ -237,7 +257,9 @@ export class PerspectiveClient {
237
257
  * calls before it answers.
238
258
  */
239
259
  async runAgent(uuid, messages, settings, options) {
240
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runAgent', { uuid, messages, ...settings }, options);
260
+ const reply = __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.runAgent', { uuid, messages, ...settings }, options);
261
+ // Without write tools the session only reads.
262
+ return settings?.writeTools?.length ? __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, reply) : reply;
241
263
  }
242
264
  /**
243
265
  * Register a neighbourhood auto-processor on this perspective. The executor's
@@ -248,11 +270,11 @@ export class PerspectiveClient {
248
270
  * Returns the processor id.
249
271
  */
250
272
  async addAutoProcessor(uuid, config) {
251
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addAutoProcessor', { ...config, uuid });
273
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addAutoProcessor', { ...config, uuid }));
252
274
  }
253
275
  /** Delete an auto-processor's config. `false` when there was none to delete. */
254
276
  async removeAutoProcessor(uuid, processorId) {
255
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeAutoProcessor', { uuid, processorId });
277
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeAutoProcessor', { uuid, processorId }));
256
278
  }
257
279
  /** Pending interpretation overlays (LLM suggestions awaiting human accept/reject). */
258
280
  async interpretationOverlays(uuid) {
@@ -264,18 +286,18 @@ export class PerspectiveClient {
264
286
  /** Accept an overlay's suggestion(s): the LLM value becomes the real value and
265
287
  * the overlay is deleted. Omit `property` to accept the whole base. */
266
288
  async acceptInterpretation(uuid, base, property) {
267
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.acceptInterpretation', { uuid, base, property });
289
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.acceptInterpretation', { uuid, base, property }));
268
290
  }
269
291
  /** Reject an overlay's suggestion(s). Omit `property` to reject the whole base
270
292
  * (a rejected `create` deletes the suggested instance). */
271
293
  async rejectInterpretation(uuid, base, property) {
272
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectInterpretation', { uuid, base, property });
294
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectInterpretation', { uuid, base, property }));
273
295
  }
274
296
  async proposeFlowTransition(uuid, instanceUri, toState, rationale, outputs) {
275
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.proposeFlowTransition', { uuid, instanceUri, toState, rationale, outputs });
297
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.proposeFlowTransition', { uuid, instanceUri, toState, rationale, outputs }));
276
298
  }
277
299
  async acceptFlowProposal(uuid, proposalUri) {
278
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.acceptFlowProposal', { uuid, proposalUri });
300
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.acceptFlowProposal', { uuid, proposalUri }));
279
301
  }
280
302
  /**
281
303
  * Withdraw this agent's own links from a proposal. Resolves to how many
@@ -283,7 +305,7 @@ export class PerspectiveClient {
283
305
  * proposal this agent opened.
284
306
  */
285
307
  async rejectFlowProposal(uuid, proposalUri) {
286
- const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectFlowProposal', { uuid, proposalUri });
308
+ const result = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectFlowProposal', { uuid, proposalUri }));
287
309
  return result.retractedLinks;
288
310
  }
289
311
  /** Re-decide a flow receipt under this perspective's own flow catalogue. */
@@ -300,49 +322,51 @@ export class PerspectiveClient {
300
322
  async flowStates(uuid, instances) {
301
323
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.flowStates', { uuid, instances });
302
324
  }
303
- /** The proposals of `instance` the calling agent's replica recorded as
304
- * fired, sorted. */
305
- async flowFired(uuid, instance) {
306
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.flowFired', { uuid, instance });
325
+ /** For each of `instances`, in order, the proposals the calling agent's
326
+ * replica recorded as fired, sorted. One call covers up to 200
327
+ * instances (more is refused with a 400); split a longer list into
328
+ * batches of 200. */
329
+ async flowFired(uuid, instances) {
330
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.flowFired', { uuid, instances });
307
331
  }
308
332
  /** Mint and store the receipt for a completed flow run. Fails while the
309
333
  * run has not settled into a terminal state, and when an output's
310
334
  * content no longer matches what the quorum committed to. */
311
335
  async mintFlowReceipt(uuid, instanceUri) {
312
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.mintFlowReceipt', { uuid, instanceUri });
336
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.mintFlowReceipt', { uuid, instanceUri }));
313
337
  }
314
338
  async addLinkExpression(uuid, link, status = 'shared', batchId) {
315
- const added = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLinkExpression', { uuid, link: linkExpressionToWire(link), status, batchId });
339
+ const added = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addLinkExpression', { uuid, link: linkExpressionToWire(link), status, batchId }));
316
340
  return LinkExpression.fromWire(added);
317
341
  }
318
342
  async updateLink(uuid, oldLink, newLink, batchId) {
319
- const updated = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.updateLink', { uuid, oldLink: linkExpressionInputToWire(oldLink), newLink, batchId });
343
+ const updated = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.updateLink', { uuid, oldLink: linkExpressionInputToWire(oldLink), newLink, batchId }));
320
344
  return LinkExpression.fromWire(updated);
321
345
  }
322
346
  async removeLink(uuid, link, batchId) {
323
347
  const { status, ...wire } = linkExpressionInputToWire(link);
324
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeLink', { uuid, link: wire, batchId });
348
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeLink', { uuid, link: wire, batchId }));
325
349
  }
326
350
  async addSdna(uuid, name, sdnaCode, sdnaType, shaclJson) {
327
- const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addSdna', { uuid, name, sdnaCode: sdnaCode || "", sdnaType, shaclJson });
351
+ const result = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addSdna', { uuid, name, sdnaCode: sdnaCode || "", sdnaType, shaclJson }));
328
352
  return typeof result === 'boolean' ? result : result.every(Boolean);
329
353
  }
330
354
  async addSdnaBatch(uuid, entries) {
331
- const result = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addSdna', { uuid, entries: entries.map(e => ({ ...e, sdnaCode: e.sdnaCode || "" })) });
355
+ const result = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.addSdna', { uuid, entries: entries.map(e => ({ ...e, sdnaCode: e.sdnaCode || "" })) }));
332
356
  return typeof result === 'boolean' ? [result] : result;
333
357
  }
334
358
  async executeCommands(uuid, commands, expression, parameters, batchId) {
335
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.executeCommands', { uuid, commands, expression, parameters, batchId });
359
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.executeCommands', { uuid, commands, expression, parameters, batchId }));
336
360
  }
337
361
  async createSubject(uuid, subjectClass, expressionAddress, initialValues, batchId) {
338
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.createSubject', { uuid, subjectClass, expressionAddress, initialValues, batchId });
362
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.createSubject', { uuid, subjectClass, expressionAddress, initialValues, batchId }));
339
363
  }
340
364
  /** Through an abstract class (#1435), the executor writes to the record's own classes. */
341
365
  async updateSubject(uuid, subjectClass, expressionAddress, values, batchId) {
342
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.updateSubject', { uuid, subjectClass, expressionAddress, values, batchId });
366
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.updateSubject', { uuid, subjectClass, expressionAddress, values, batchId }));
343
367
  }
344
368
  async removeSubject(uuid, subjectClass, expressionAddress, batchId) {
345
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeSubject', { uuid, subjectClass, expressionAddress, batchId });
369
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.removeSubject', { uuid, subjectClass, expressionAddress, batchId }));
346
370
  }
347
371
  /**
348
372
  * Validated writes (`perspective.instance*`): the executor checks each against the class's
@@ -362,23 +386,23 @@ export class PerspectiveClient {
362
386
  * it to keep the calls that succeeded.
363
387
  */
364
388
  async instanceCreate(uuid, body) {
365
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceCreate', { uuid, ...body });
389
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceCreate', { uuid, ...body }));
366
390
  }
367
391
  /** Sets the given single-valued properties; the others stay. See {@link instanceCreate}. */
368
392
  async instanceUpdate(uuid, body) {
369
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceUpdate', { uuid, ...body });
393
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceUpdate', { uuid, ...body }));
370
394
  }
371
395
  /** Removes the instance and every link to and from it. See {@link instanceCreate}. */
372
396
  async instanceRemove(uuid, body) {
373
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceRemove', { uuid, ...body });
397
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceRemove', { uuid, ...body }));
374
398
  }
375
399
  /** Adds an item to a collection (a no-op when it is a member). See {@link instanceCreate}. */
376
400
  async instanceAddToCollection(uuid, body) {
377
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceAddToCollection', { uuid, ...body });
401
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceAddToCollection', { uuid, ...body }));
378
402
  }
379
403
  /** Removes an item's membership link from a collection. See {@link instanceCreate}. */
380
404
  async instanceRemoveFromCollection(uuid, body) {
381
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceRemoveFromCollection', { uuid, ...body });
405
+ return __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.instanceRemoveFromCollection', { uuid, ...body }));
382
406
  }
383
407
  async getSubjectData(uuid, subjectClass, expressionAddress) {
384
408
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getSubjectData', { uuid, subjectClass, expressionAddress });
@@ -414,11 +438,12 @@ export class PerspectiveClient {
414
438
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getShacl', { uuid, name });
415
439
  }
416
440
  /**
417
- * Retrieve all SHACL shapes in one call. Returns an array of
418
- * `{name, shapeUri, links}` — one entry per shape (one RPC call).
441
+ * Retrieve SHACL shapes in one call: every shape, or only those in
442
+ * `names` (unknown names are left out). Returns `{name, shapeUri, links}`
443
+ * per shape.
419
444
  */
420
- async getAllShacl(uuid) {
421
- return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getAllShacl', { uuid });
445
+ async getAllShacl(uuid, names) {
446
+ return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.getAllShacl', { uuid, names });
422
447
  }
423
448
  // ExpressionClient functions, needed for Subjects:
424
449
  async getExpression(expressionURI) {
@@ -438,7 +463,7 @@ export class PerspectiveClient {
438
463
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.createBatch', { uuid });
439
464
  }
440
465
  async commitBatch(uuid, batchId) {
441
- const diff = await __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.commitBatch', { uuid, batchId });
466
+ const diff = await __classPrivateFieldGet(this, _PerspectiveClient_instances, "m", _PerspectiveClient_wrote).call(this, uuid, __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").call('perspective.commitBatch', { uuid, batchId }));
442
467
  return LinkExpressionMutations.fromWire(diff);
443
468
  }
444
469
  /**
@@ -456,7 +481,21 @@ export class PerspectiveClient {
456
481
  return __classPrivateFieldGet(this, _PerspectiveClient_apiClient, "f").onReconnect(callback);
457
482
  }
458
483
  }
459
- _PerspectiveClient_apiClient = new WeakMap(), _PerspectiveClient_expressionClient = new WeakMap(), _PerspectiveClient_neighbourhoodClient = new WeakMap(), _PerspectiveClient_aiClient = new WeakMap(), _PerspectiveClient_instances = new WeakSet(), _PerspectiveClient_released =
484
+ _PerspectiveClient_apiClient = new WeakMap(), _PerspectiveClient_expressionClient = new WeakMap(), _PerspectiveClient_neighbourhoodClient = new WeakMap(), _PerspectiveClient_aiClient = new WeakMap(), _PerspectiveClient_sparqlInFlight = new WeakMap(), _PerspectiveClient_writeGeneration = new WeakMap(), _PerspectiveClient_instances = new WeakSet(), _PerspectiveClient_wrote =
485
+ /**
486
+ * Await a write to `uuid`, then start a new write generation for it
487
+ * (also when the write failed: it may still have changed the perspective).
488
+ * Calls of {@link querySparql} already waiting keep sharing their RPC; an
489
+ * identical call started from now on makes its own.
490
+ */
491
+ async function _PerspectiveClient_wrote(uuid, write) {
492
+ try {
493
+ return await write;
494
+ }
495
+ finally {
496
+ __classPrivateFieldGet(this, _PerspectiveClient_writeGeneration, "f").set(uuid, (__classPrivateFieldGet(this, _PerspectiveClient_writeGeneration, "f").get(uuid) ?? 0) + 1);
497
+ }
498
+ }, _PerspectiveClient_released =
460
499
  /** A subscribe call that failed (timed out, aborted, refused) leaves no live
461
500
  * query on the executor that nobody holds. The client minted its id, so it
462
501
  * disposes it without the reply. A timeout or an abort sends `request.cancel`
@@ -1,5 +1,6 @@
1
1
  import { PerspectiveClient } from "./PerspectiveClient";
2
2
  import type { EventMap, ScopedEventName } from "../generated/api/Events";
3
+ import type { FlowFiredEntry } from "../generated/api/FlowFiredEntry";
3
4
  import type { FlowFireOutcome, FlowMintedReceipt, FlowOutputRef, FlowProposeResult, FlowReceiptVerdict, FlowStateEntry, FlowValidOutput } from "./FlowInstance";
4
5
  import { CallOptions } from "../apiClient";
5
6
  import { Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkMutations } from "../links/Links";
@@ -371,11 +372,14 @@ export declare class PerspectiveProxy {
371
372
  */
372
373
  flowStates(instances?: string[]): Promise<FlowStateEntry[]>;
373
374
  /**
374
- * The proposals of `instance` whose votes settled an edge, as this
375
- * agent's executor recorded them — the flow's history, sorted by URI.
375
+ * For each of `instances`, in order, the proposals whose votes settled an
376
+ * edge, as this agent's executor recorded them — the flow's history,
377
+ * sorted by URI (`fired: []` when none). One call covers up to 200
378
+ * instances (the executor refuses more with a 400); split a longer list
379
+ * into batches of 200.
376
380
  * Replaces the `resolvedAs` property proposals used to carry.
377
381
  */
378
- flowFired(instance: string): Promise<string[]>;
382
+ flowFired(instances: string[]): Promise<FlowFiredEntry[]>;
379
383
  /**
380
384
  * Called whenever a flow instance on this perspective changes state on
381
385
  * this agent's executor, or an edge settles: `{ instance, from, to,
@@ -432,8 +436,11 @@ export declare class PerspectiveProxy {
432
436
  * keep its blocking thread busy until it completes; what's saved is the
433
437
  * serialise + network + client-deserialise tax on the result. Aborted
434
438
  * calls reject with `DOMException('Aborted', 'AbortError')` — match
435
- * `fetch()` for handling. Cached results bypass the round-trip entirely
436
- * and are returned synchronously, ignoring the signal.
439
+ * `fetch()` for handling. A call with `options` makes its own RPC.
440
+ *
441
+ * **Sharing:** concurrent identical calls without `options` share one RPC;
442
+ * each caller gets its own result object. Nothing is cached once the
443
+ * call settles: use a live query for repeated reads of the same data.
437
444
  *
438
445
  * @param query - SPARQL query string (read-only operations only)
439
446
  * @param options - Optional call options (e.g. AbortSignal for cancellation)
@@ -451,11 +458,11 @@ export declare class PerspectiveProxy {
451
458
  * query over their union, whose rows carry `__subjectClass` and
452
459
  * `__subjectClasses` (#1238)
453
460
  * @param queryJson - Structured query as JSON string
454
- * @returns Object with `instances` array and `totalCount`
461
+ * @returns Object with `instances` array, and `totalCount` when the query sets `count: true`
455
462
  */
456
463
  modelQuery(className: string | string[], queryJson: string, options?: CallOptions): Promise<{
457
464
  instances: any[];
458
- totalCount: number;
465
+ totalCount?: number;
459
466
  }>;
460
467
  /** Resolve each URI to the names of every subject class it is an instance of.
461
468
  *
@@ -808,12 +815,14 @@ export declare class PerspectiveProxy {
808
815
  */
809
816
  getShaclTargetClass(name: string): Promise<string | undefined>;
810
817
  /**
811
- * Get all SHACL shapes stored in this Perspective (one RPC call).
812
- * The executor resolves all shapes in-process and returns them in bulk.
818
+ * Get the SHACL shapes stored in this Perspective in one RPC call: all of
819
+ * them, or only those named in `names` (unknown names are left out).
813
820
  * A shape that fails to decode is skipped with a `console.warn`, so it
814
821
  * does not hide the others.
815
822
  */
816
- getAllShacl(): Promise<Array<{
823
+ getAllShacl(options?: {
824
+ names?: string[];
825
+ }): Promise<Array<{
817
826
  name: string;
818
827
  shape: SHACLShape;
819
828
  }>>;